diff --git a/.gitignore b/.gitignore
index e61911d59..380c603b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,6 +38,9 @@ temp*build*/
 /target/
 /logs
 /.codegraph/
+/.playwright-cli/
+**/.playwright-cli/
+/output/playwright/
 /server-rs/crates/*/logs/
 .worktrees/
 .rag/
diff --git a/CONTEXT.md b/CONTEXT.md
index 233cde60e..93a8f0dda 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -12,6 +12,22 @@ _Avoid_: 默认对话式 Agent 工作台、默认轻输入 Agent 工作台、复
 角色形象、UI 背景、容器、封面、分享图等单张图资产的统一输入与重生成方式，统一通过 `CreativeImageInputPanel` 表达上传、AI 重绘、参考图、历史图和删除确认。
 _Avoid_: 在玩法页面内手写上传、参考图、重绘、预览、删除确认
 
+**图片画布工程**:
+独立 `/editor` 中可保存、恢复和继续编辑的图片画布工作状态，包含画布视图、图层布局和资源引用；用于多图对比、生成结果衍生和画布级编辑，不替代玩法页面内的单图资产编辑。
+_Avoid_: 玩法结果页单图槽位、发布态作品、只存在前端内存里的临时画布
+
+**画布资源**:
+图片画布工程中可被一个或多个图层引用的图片资源记录，保存 OSS 对象引用、上传 / 生成来源、提示词、模型、任务和尺寸等资源元数据；同一资源可以在工程布局中出现多次。
+_Avoid_: 图层位置、前端 hover / selected 状态、直接内嵌图片二进制
+
+**图层布局**:
+图片画布工程中描述资源实例如何摆放的画布结构，包含 resourceId、位置、尺寸、缩放、层级和选中所需的稳定图层 ID；布局属于工程快照，不属于画布资源本身。
+_Avoid_: 把同一资源的全局元数据和某一次摆放坐标混在同一条资源记录里
+
+**生成资源**:
+由图片生成或图片修改流程产生的画布资源，必须记录来源资源、提示词、实际提示词、模型、provider、任务 ID 和生成时间；本期 `/editor` 的生成修改先允许 mock 生成资源，但仍按生成资源元数据形状保存。
+_Avoid_: 无来源的静态素材、只显示在 UI 但不落工程资源记录的生成结果
+
 **系列素材图集生成**:
 一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。
 _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO
diff --git a/TRACKING.md b/TRACKING.md
new file mode 100644
index 000000000..9d577ebd0
--- /dev/null
+++ b/TRACKING.md
@@ -0,0 +1,176 @@
+# 图片画布编辑器 Lovart 化执行跟踪
+
+更新时间：`2026-06-17`
+
+## 目标
+
+- 先落文档、测试用例和进度跟踪文件。
+- 再实施 `/editor/canvas` 的 Lovart 风格画布交互、缩放二级菜单、吸附线、元数据窗口、真实生成 / 修改入口和工程 / 画布持久化。
+
+## 拆分口径
+
+- `docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md` 中的二十七个“阶段模块”是原始计划项，用来描述目标边界。
+- 本文件验证记录里的“执行批次”按每次实际修改、验证、提交和推送递增，包含原始计划项落地、计划外回归修复、组件复用、测试迁移和后续模型收口。
+- 因此“第四十一执行批次”不代表原始计划有四十一个阶段；它表示已完成并推送的第四十一次前端拆分相关增量。
+- 当前原始二十七个计划项已经覆盖到第二十七阶段模块，后续执行批次属于对已拆模块的深化收口或回归修复。
+
+## 进度
+
+| 工作项 | 状态 | 记录 |
+| --- | --- | --- |
+| 文档 | 已完成 | 已补领域词、技术方案和后端表 / API 边界。 |
+| 测试用例 | 已完成 | 已补前端交互测试和 editor project client 测试。 |
+| 后端持久化 | 已完成 | 已新增 editor project/resource 表、SpacetimeDB procedure、spacetime-client facade 与 api-server BFF。 |
+| 前端交互 | 已完成 | 已实现缩放菜单、工具模式、Space 抓手、中键平移、吸附线、元数据弹窗和右侧真实修改结果。 |
+| 素材库增强 | 已完成 | 已实现账号级素材库持久化、文件夹新建 / 折叠 / 重命名 / 删除、多文件上传、拖拽定向上传、素材框选与批量删除。 |
+| 画布增强 | 已完成 | 已实现拖拽上传到画布并创建图层、图层打组、Ctrl/Cmd 滚轮缩放、普通滚轮纵向滚动和小地图拖拽移动视图。 |
+| 前端拆分 | 进行中 | 已新增前端拆分计划，抽出类型、画布模型、生成模型、导出模型和素材 / 图层整合侧栏视图，主视图保留状态编排与跨画布状态机。 |
+| 验证 | 已完成 | 聚焦测试、类型检查、Rust 检查、schema guard、编码检查、diff 空白检查和浏览器 smoke 已通过。 |
+
+## 待办清单
+
+- [x] 更新图片画布编辑器技术方案，明确 v2 范围。
+- [x] 补充 `/editor/canvas` 领域词，区分图片画布工程和单图资产编辑。
+- [x] 添加前端组件交互测试。
+- [x] 添加 editor project API client 测试。
+- [x] 新增 `editor_project`、`editor_canvas` 与 `editor_project_resource` 表。
+- [x] 同步 SpacetimeDB migration 表清单、生成绑定和后端架构表目录。
+- [x] 新增 api-server `/api/editor/projects*` BFF。
+- [x] 接入前端自动保存与资源创建 API。
+- [x] 实现 Lovart 风格缩放菜单和快捷键。
+- [x] 实现 AI 画布底部工具栏、工具模式和临时抓手。
+- [x] 实现核心吸附线和拖拽吸附。
+- [x] 实现生成资源元数据窗口和真实修改右侧结果。
+- [x] 执行并记录验证命令。
+- [x] 新增 `/project` 项目页，接入项目列表、单项重命名 / 删除、批量选择和批量删除。
+- [x] 接入“我的”页项目入口与 `/editor/canvas?projectid=<projectId>` 精准加载。
+- [x] 新增账号级素材库表、API、前端服务和编辑器接入。
+- [x] 素材文件夹支持新建、折叠、重命名和删除。
+- [x] 上传按钮与拖拽上传均支持多文件；拖到文件夹 / 素材行进入对应文件夹，拖到画布进入默认文件夹并创建图层。
+- [x] 素材选择模式支持框选多选和批量删除。
+- [x] 图层面板支持对当前选中图层打组并持久化 groupId。
+- [x] 小地图支持拖拽移动画布视图。
+- [x] 滚轮语义调整为普通滚轮纵向滚动，Ctrl/Cmd 滚轮缩放并阻止浏览器缩放。
+
+## 决策记录
+
+- `/editor/canvas` 的长期领域对象命名为“图片画布工程的画布入口”。
+- project 保存工程元数据；canvas 保存 viewport 与图层布局；资源表保存 OSS 引用和上传 / 生成元数据。
+- 本期工程与资源持久化真实落库；图片生成 / 修改已接入 api-server VectorEngine BFF，暂不接入计费和队列进度。
+- `适合视图` 的语义为显示画布所有可见元素。
+- 吸附范围为核心对齐：左右 / 上下边缘和水平 / 垂直中心线。
+- 缩放控件采用 Lovart 风格百分比按钮和二级菜单。
+
+## 验证记录
+
+- `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
+- `npm run test -- src/services/image-editor/editorProjectClient.test.ts`
+- `npm run test -- src/routing/appPageRoutes.test.ts`
+- `npm run typecheck`
+- `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
+- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
+- `npm run check:spacetime-schema`
+- `npm run check:encoding`
+- `git diff --check`
+- Headless Playwright smoke：`http://127.0.0.1:10000/editor` 可展示画布、缩放菜单、底部工具栏和图片工具栏；只启动 `dev:web` 时 `/api/*` 代理 500 属于未启动后端的预期现象。
+- 2026-06-12 Lovart 布局修正 smoke：`http://127.0.0.1:10000/editor` 已移除左侧竖向工具栏和右侧独立图层栏；素材、已生成文件、图层统一收在左侧可折叠面板，中央画布和周边面板保持浅色一体布局；截图留存于 `output/playwright/editor-left-integrated-light.png`。
+- 2026-06-12 外圈背景修正 smoke：`http://127.0.0.1:10000/editor` 的编辑器宿主和画布根容器已铺成同一块白色工作台，不再通过圆角边框露出底部平台背景；截图留存于 `output/playwright/editor-no-outer-background.png`。
+- 2026-06-12 画布背景与原生菜单修正 smoke：`http://127.0.0.1:10000/editor` 已拦截编辑器区域右键菜单，禁用长按文本选择 / iOS callout，并移除画布网格线与棋盘格底纹；截图留存于 `output/playwright/editor-plain-background.png`。
+- 2026-06-12 Lovart 面板与外层 padding 修正：`/editor` 外层 `platform-ui-shell` 已按 `image-editor` stage 使用 `p-0 bg-white`，其它页面保留原 padding；已生成文件和图层改为画布左下入口按钮触发的浮层面板，不再堆叠在左侧素材栏；浏览器样式检查确认 shell padding 为 `0px`、画布背景无 `background-image`，截图留存于 `output/playwright/editor-lovart-panel-popup-final.png`。
+- 2026-06-12 侧栏切换修正：删除“已生成文件”入口，删除侧栏内展开 / 折叠按钮；画布左下仅保留“素材”和“图层”入口，二者复用同一个左侧栏，点击当前已打开入口会关闭侧栏。
+- 2026-06-12 工具栏能力修正：删除底部“局部修改工具”入口；上传工具接入隐藏文件选择并将图片加入画布图层；图片浮动工具栏的删除按钮改为真实删除当前图层。
+- 2026-06-12 生成工具修正：移除拼图素材的生成图 mock 元数据，使其作为普通素材显示；底部生成工具改为先打开生成图片对话框，再进入生成中状态并把生成结果加入画布，生成结果保留元数据与修改入口。
+- 2026-06-13 真实生图修正：`/api/editor/images/generations` 和 `/api/editor/images/edits` 统一走 api-server VectorEngine `gpt-image-2` BFF；前端不再创建 mock 成功图，生成 / 修改失败会留在对话框内显示错误；生成图右上角 `{}` 元数据按钮可直接点击打开元数据窗口。
+- 2026-06-13 素材库修正：素材栏按文件夹分组，文件夹支持折叠和新建；上传入口可定向到当前文件夹，上传素材进入素材库并支持删除，内置素材只保留添加和重命名。
+- 2026-06-13 生图鉴权修正：编辑器工程和真实生图请求不再使用禁止 refresh 的局部鉴权策略，可通过 refresh cookie 静默补 access token；真实生图遇到 401 / 403 时弹窗显示“请先登录后再生成图片”，不再暴露后端 requestId 主文案。
+- 2026-06-13 Lovart 生图交互修正：纯文本生图不再使用居中弹窗，点击底部生成工具后在画布中心显示 `Image Generator` 占位框，并在占位框下方显示跟随式生成输入框、参考图入口、比例和模型占位按钮；生成成功后真实图片落在占位框位置。
+- 2026-06-13 Lovart 生图 smoke：`http://127.0.0.1:10003/editor` 点击底部生成工具后已显示画布内占位框和底部浮动输入框，截图留存于 `output/playwright/editor-lovart-generation-composer.png`。
+- 2026-06-13 生图占位交互修正：`Image Generator` 占位框支持拖拽移动，生成输入框跟随占位框；生成成功图层沿用拖拽后的占位位置，生成输入框继续锚定在新生成图片下方，点击其它图片或画布空白不会自动关闭。
+- 2026-06-13 生图锚定 smoke：`http://127.0.0.1:10003/editor` 中占位框拖拽前后坐标从 `(616,217)` 到 `(712,289)`，生成输入框同步从 `(516,571)` 到 `(612,643)`，保持锚定在生成对象下方；截图留存于 `output/playwright/editor-generation-composer-anchored.png`。
+- 2026-06-13 Lovart 小地图与背景色修正：画布左下角补回背景色圆点、小地图开关和小地图预览；小地图展示图层缩略分布与当前视口框，点击执行显示所有元素，背景色菜单可切换工作区底色且不恢复网格 / 棋盘底纹。
+- 2026-06-13 小地图与背景色 smoke：`http://127.0.0.1:10003/editor` 可见左下角小地图、背景色按钮和小地图开关；切换暖灰后画布工作区 `background-color` 为 `rgb(243, 240, 234)`，`background-image` 仍为 `none`；截图留存于 `output/playwright/editor-minimap-background-warm.png`。
+- 2026-06-13 路由与数据归属修正：图片画布页面路由改为 `/editor/canvas`；新增 `editor_canvas` 表作为 project 下的画布数据表，当前工程创建时同步创建默认画布，保存 layout 时写入默认画布，API 响应同时返回 `project.canvas` 和兼容顶层 `viewport/layers`。
+- 2026-06-13 项目页修正：新增 `/project` 作为图片画布工程列表入口；从“我的”页进入项目页，项目卡片进入 `/editor/canvas?projectid=<projectId>`，并补齐项目列表、重命名、删除和批量删除 API。`GET /api/editor/projects` 在重启后的 api-server 上返回未登录 401，不再是旧进程的 405；`/project` 前端路由 smoke 可渲染项目页白底布局。
+- 2026-06-14 组件复用修正：项目页重命名弹窗改为复用 `UnifiedModal`、`PlatformTextField` 和 `PlatformActionButton`，删除项目页局部 modal / input 样式，避免同类弹窗和表单 chrome 重复实现。
+- 2026-06-14 组件复用修正：新增 `PlatformFloatingMenu` / `PlatformFloatingMenuItem`，项目卡片右下角更多菜单改为复用平台浮层菜单原语；验证命令：`npm run test -- src/components/common/PlatformFloatingMenu.test.tsx src/components/project/ProjectGalleryView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：`PlatformFloatingMenu` 增加菜单标签和四向定位，编辑器顶部缩放菜单改为复用同一浮层菜单原语；验证命令：`npm run test -- src/components/common/PlatformFloatingMenu.test.tsx src/components/project/ProjectGalleryView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器生成图元数据弹窗改为复用 `UnifiedModal`，不再手写元数据弹窗遮罩、dialog role 和关闭按钮；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/UnifiedModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器“修改图片”弹窗改为复用 `UnifiedModal`，删除编辑器局部 modal backdrop、dialog role、header 和关闭按钮样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/UnifiedModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：新增 `PlatformBatchActionToolbar`，项目页选择模式底部批量操作栏改为复用平台批量工具栏原语；验证命令：`npm run test -- src/components/common/PlatformBatchActionToolbar.test.tsx src/components/project/ProjectGalleryView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：项目页读取失败提示改为复用 `PlatformStatusMessage`，页面局部错误样式只保留布局间距；验证命令：`npm run test -- src/components/project/ProjectGalleryView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器生成 / 修改流程中的生成中与失败提示改为复用 `PlatformStatusMessage`，删除局部状态条颜色和错误变体样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器画布背景色菜单改为复用 `PlatformFloatingMenu` 和 `PlatformFloatingMenuItem`，删除局部菜单容器定位 / 边框 / 阴影样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformFloatingMenu.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器“修改图片”弹窗提交按钮改为复用 `PlatformActionButton`，删除局部提交按钮颜色、边框和禁用态样式；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 组件复用修正：项目卡片预览改为复用 `PlatformMediaFrame`，删除项目页局部预览框比例、图片填充和背景样式；验证命令：`npm run test -- src/components/project/ProjectGalleryView.test.tsx src/components/common/PlatformMediaFrame.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-14 素材库与画布持久化修正：新增 `editor_asset_folder` / `editor_asset` 账号级素材库表、SpacetimeDB procedure、spacetime-client facade 和 api-server `/api/editor/assets*` BFF；编辑器接入文件夹新建 / 折叠 / 重命名 / 删除、素材重命名 / 删除、多文件上传、拖拽定向上传、拖入画布生成图层、素材框选批量删除、图层打组、小地图拖拽、普通滚轮纵向滚动与 Ctrl/Cmd 滚轮缩放。验证命令：`npm run spacetime:generate -- --rust-only`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`git diff --check`。
+- 2026-06-14 组件复用修正：编辑器 `EditorIconButton` 改为委托 `PlatformIconButton` 的薄包装，保留编辑器局部 class 与调用方式，但不再维护重复的原生图标按钮可访问性和基础 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器生成输入框的提交按钮改为复用 `PlatformActionButton`，仅保留生成器局部尺寸和 Lovart 式浅灰覆盖，不再直接维护原生 submit 按钮基础 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器生成输入框的“参考图”按钮改为复用 `PlatformIconButton variant="surfaceFloating"`，用 children 承载短标签，仅保留生成器局部尺寸和浅灰覆盖；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器生成图右上角元数据角标改为复用 `PlatformIconButton asChild="spanButton"`，保留嵌套在图层按钮内的合法 DOM 结构，同时把 Enter / Space 键盘触发和 `darkMini` chrome 收口到共享组件；验证命令：`npm run test -- src/components/common/PlatformIconButton.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器画布内生成输入框和“修改图片”弹窗提示词改为复用 `PlatformTextField variant="textarea"`，删除编辑器里按标签选择器手写 textarea 基础输入 chrome 的做法，仅保留生成器局部尺寸和 Lovart 式覆盖；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformTextField.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：新增 `PlatformInlineOptionButton`，编辑器生成输入框里的比例和模型选择 pill 改为复用平台内联选项按钮原语，删除两个局部按钮重复维护基础 inline chrome 的做法；验证命令：`npm run test -- src/components/common/PlatformInlineOptionButton.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：`PlatformEmptyState` 增加 `asChild="button"` 形态，项目页空列表“新建项目”卡片改为复用平台空态原语，避免项目页单独维护可点击空态卡片基础 chrome；验证命令：`npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/project/ProjectGalleryView.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器顶部缩放百分比触发器改为复用 `PlatformInlineOptionButton`，让缩放菜单入口和生成器比例 / 模型 pill 共用“当前选项触发菜单”的按钮原语；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformInlineOptionButton.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器左下面板 dock 的画布背景色入口改为复用 `PlatformIconButton`，用色块作为 icon 承载当前背景色，和素材 / 图层 / 小地图入口保持同一图标按钮原语；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器素材侧栏的新建文件夹、文件夹重命名和素材重命名输入框改为复用 `PlatformTextField`，输入框局部样式改为明确 class 覆盖，不再按 `input` 标签选择器重复维护基础输入 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformTextField.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：编辑器侧栏素材和图层缩略图通过 `SidebarMediaItem` 改为复用 `PlatformMediaFrame`，删除缩略图内部图片填充的重复 CSS，统一媒体预览框和 fallback 结构；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformMediaFrame.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：画布图片 hover 尺寸标签改为复用 `PlatformPillBadge tone="lightOverlay"`，局部 CSS 只保留定位和深色覆盖，不再重复维护 badge 的圆角、字号和基础排版；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformPillBadge.test.tsx`、`npm run typecheck`。
+- 2026-06-14 组件复用修正：生成跟随框的关闭按钮改为复用 `PlatformIconButton variant="surfaceFloating"`，编辑器薄包装 `EditorIconButton` 增加 variant 透传，删除局部关闭按钮基础 chrome；验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`。
+- 2026-06-16 编辑器回归修正：工程 / 素材 / 上传等编辑器请求恢复全局 401 / 403 登录弹窗；未登录上传会先弹登录并在登录后续传；画布背景入口恢复为 `画布背景设置` 面板，支持预设色、自定义颜色、HEX 输入、非法值不应用、恢复默认和 Escape 关闭。验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器 smoke：`http://127.0.0.1:10006/editor/canvas` 未登录打开 `账号入口`，登录后上传素材成功，背景面板打开后点击“暖灰”使画布背景变为 `rgb(243, 240, 234)`。
+- 2026-06-17 前端拆分第一执行批次：新增 `ImageCanvasEditorTypes`、`ImageCanvasEditorModel`、`ImageCanvasGenerationModel` 和 `ImageCanvasExportModel`，把类型、画布快照 / 吸附 / 背景、生成输入快照和导出元数据规则从 `ImageCanvasEditorView` 抽出；新增模型层单测，主视图从 8286 行降至 7054 行。
+- 2026-06-17 浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录打开工程和未登录上传均弹出 `账号入口`；关闭登录后点击 `画布背景色` 打开 `画布背景设置` 面板，点击 `暖灰` 后画布背景为 `rgb(243, 240, 234)`；登录开发账号后上传图片成功进入 `项目素材`，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第二执行批次：新增 `ImageCanvasSidebarView`，把素材 / 图层共用左侧整合面板从主视图抽出；上传链路、登录弹窗、素材拖到画布、持久化、图层历史和右键菜单状态机仍保留在主视图，避免过度拆分。验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx`、`npm run typecheck`。
+- 2026-06-17 侧栏拆分浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`；`画布背景色` 打开 `画布背景设置` dialog，包含预设、自定义颜色、HEX 和恢复默认；使用临时开发账号登录后上传图片成功进入 `项目素材`，点击素材可添加到画布，切换 `图层` 侧栏后能看到同一图片图层，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第三执行批次：新增 `ImageCanvasStageView`，把画布工作区视觉树、图层渲染、生成占位框、右键菜单、左下 dock、小地图和底部 AI 工具栏从主视图抽出；拖拽 / 缩放、历史、上传、登录、生成提交、素材持久化和右键命令仍保留在主视图，避免拆散状态机。
+- 2026-06-17 舞台拆分浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`；关闭登录后点击 `画布背景色` 打开完整 `画布背景设置` dialog，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)`；使用临时开发账号密码登录后上传 `smoke.png` 成功进入 `项目素材`，点击素材添加到画布，切换 `图层` 后显示同一图层，图片浮动工具栏、小地图和 `AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第四执行批次：新增 `ImageCanvasGenerationComposerView`，把生成图片、生成规范、生成角色形象、生成图标素材、快速编辑、角色动画和修改图片弹窗从主视图抽出；生成提交、上传 input、引用选择、占位框拖拽、结果回写、历史和画布状态机仍保留在主视图。验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx`、`npm run typecheck`。
+- 2026-06-17 生成面板拆分浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空浏览器数据后未登录刷新弹出 `账号入口`；关闭登录后 `画布背景色` 打开 `画布背景设置`，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)`；点击 `生成工具` 后画布显示 `Image Generator` 占位框和 `生成图片` 跟随对话框，`AI画布工具栏` 保持可见；使用临时开发账号密码登录后上传素材成功，点击素材可添加到画布，切换 `图层` 面板可看到对应图层。
+- 2026-06-17 前端拆分第五执行批次：新增 `ImageCanvasLayerCommandModel`，把右键图层目标解析、复制 / 粘贴 / 创建副本、层级移动、分组 / 解组、显隐、锁定、翻转和删除的数据规则从主视图抽出；主视图只保留历史、选中态、菜单关闭、元数据清理和导出下载副作用。验证命令：`npm run test -- src/components/image-editor/ImageCanvasLayerCommandModel.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`，背景入口打开完整 `画布背景设置` 面板；登录后上传素材成功，点击素材可加入画布，图片右键打开 `图片功能面板`，创建副本、水平翻转、锁定和隐藏均生效，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第六执行批次：新增 `ImageCanvasInteractionModel`，把适合视图、中心缩放、普通滚轮纵向滚动、Ctrl / Cmd 滚轮缩放、坐标换算、框选命中、平移、生成占位框拖拽、图层拖拽吸附、小地图投影、小地图点击定位和小地图拖拽视图移动的纯规则从主视图抽出；主视图保留事件、pointer capture、history、生成对象回写、选中态和状态更新。验证命令：`npm run test -- src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 登录态刷新后素材、画布图层、小地图和 `AI画布工具栏` 保持可见，Ctrl 滚轮从 110% 缩放到 121%，普通滚轮不改变缩放，浏览器控制台无 passive wheel 错误。
+- 2026-06-17 新增素材持久化修正：素材库图片、上传到画布、生成图、修改图和图标素材加入画布时会先用当前图层快照更新本地画布，再在资源创建完成后立刻保存带真实 `resourceId` 的 layout，避免资源创建异步返回时把空 `layers` 写回工程。验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录弹出 `账号入口`，登录后上传素材、点击素材加入画布并刷新，画布图片和 `AI画布工具栏` 均保持可见。
+- 2026-06-17 前端拆分第七执行批次：新增 `useCanvasHistory`，把画布历史快照、撤销、重做、历史栈长度限制和 `canUndo` / `canRedo` 派生状态从主视图抽出；主视图只在具体动作前捕获历史，并注入恢复快照后的菜单 / hover / 框选 / 拖拽清理。验证命令：`npm run test -- src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`。
+- 2026-06-17 前端拆分第八执行批次：新增 `useImageCanvasProjectPersistence`，把项目加载、`projectId` 状态、未就绪资源队列、工程资源创建、资源创建后即时保存和 450ms 自动保存从主视图抽出；新增 hook 单测锁定新增图层资源创建后保存真实 `resourceId` 的 layout。验证命令：`npm run test -- src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`。
+- 2026-06-17 前端拆分第九执行批次：新增 `useCanvasGenerationDialogs`，把画布生成对象的 active / inactive 注册表、归档、激活、按 id 更新 / 删除、按图层清理和生成中最新占位框查询从主视图抽出；主视图继续保留生成提交、结果落图、quick edit 和跨图层副作用。同步把 `画布背景设置` 调整为 Lovart 式紧凑色板弹层。验证命令：`npm run test -- src/components/image-editor/useCanvasGenerationDialogs.test.tsx src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后未登录弹出 `账号入口`，关闭后点击 `画布背景色` 显示色域、色相条、圆形预设和 HEX 输入，点击 `生成工具` 后画布显示 `Image Generator` 占位框和 `生成图片` 对话框，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第十执行批次：新增 `useImageCanvasAssetLibrary`，把账号级素材库加载、文件夹新建 / 折叠 / 重命名 / 删除、素材重命名 / 删除、素材选择模式、框选、多选删除、素材拖到文件夹和素材库 401 登录弹窗从主视图抽出；主视图继续保留上传读取、上传进度、拖到画布坐标、画布图层创建和工程资源持久化。新增 hook 单测覆盖素材库归一化、401 登录、新建文件夹临时 id 替换、素材移动、删除回调和多选删除。验证命令：`npm run test -- src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`，背景面板点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后生成占位和 `生成图片` 对话框出现且 `AI画布工具栏` 保持可见；登录临时开发账号后上传图片成功进入 `项目素材`，点击素材加入画布，切换 `图层` 可看到对应图层，控制台无前端 error。
+- 2026-06-17 前端拆分第十一执行批次：新增 `ImageCanvasFileModel` 和 `useImageCanvasUploadWorkflow`，把隐藏上传 input、上传目标分发、未登录续传、上传占位卡片、素材落库、拖到画布建层、生成参考图上传从主视图抽出；主视图保留画布 drop 外层判断和项目资源持久化注入。验证命令：`npm run test -- src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`，登录临时开发账号后 `画布背景设置` 面板点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后显示 `Image Generator` 占位框和 `生成图片` 对话框且 `AI画布工具栏` 保持可见；上传图片后素材数增加，点击素材加入画布，切换 `图层` 面板可看到 2 个图层，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第十二执行批次：新增 `ImageCanvasGenerationLayerModel`，把普通生图、修改图片、快速编辑和图标素材批量生成结果落画布的图层 id、临时 resourceId、标题、位置、原始分辨率尺寸、zIndex、source metadata、源图关联和 `generationInputs` 纯规则从主视图抽出；主视图继续负责 API 提交、生成对象状态、资源持久化、选中态、侧栏和适合视图副作用。验证命令：`npm run test -- src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后未登录刷新弹出 `账号入口`，登录临时开发账号后 `画布背景设置` 面板保留色相 / 自定义颜色 / 预设 / HEX / 恢复默认，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后显示 `Image Generator` 占位框和 `生成图片` 对话框且 `AI画布工具栏` 保持可见；真实上传图片后素材数从 2 增至 3，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第十三执行批次：新增 `useImageCanvasAssetExportWorkflow`，把画布素材导出状态、单图右键导出、整包 ZIP 组包、图片去重、读取失败记录、metadata / manifest 和下载链接副作用从主视图抽出；主视图保留右键目标解析和状态提示渲染。验证命令：`npm run test -- src/components/image-editor/useImageCanvasAssetExportWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后未登录刷新弹出 `账号入口`，登录临时开发账号后下载按钮启用，点击后触发真实下载 `未命名画布-画布素材-20260617.zip` 并显示导出状态；背景设置点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后 `生成图片` 对话框出现且 `AI画布工具栏` 保持可见，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第十四执行批次：新增 `useImageCanvasLayerCommands`，把画布剪贴板、右键目标解析、复制 / 剪切 / 粘贴、创建副本、层级移动、分组 / 解组、显隐、锁定、翻转、删除选中图层、按 id 删除和单图导出委托从主视图抽出；主视图保留菜单定位、画布事件、生成、上传、项目持久化和实际导出下载。验证命令：`npm run test -- src/components/image-editor/useImageCanvasLayerCommands.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后未登录刷新弹出 `账号入口`，关闭后 `画布背景色` 打开完整 `画布背景设置`，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后 `Image Generator` 占位框、`生成图片` 对话框和 `AI画布工具栏` 均可见；登录临时开发账号后新标签素材、画布图层、返回项目入口、小地图和底部工具栏可见，控制台无前端 error。
+- 2026-06-17 前端拆分第十五执行批次：新增 `useImageCanvasGenerationWorkflow`，把生成入口、规范 / 角色 / 图标 / 修改 / 快速编辑 / 角色动画状态机、真实生成提交、结果落图、失败恢复和删除图层后的生成态清理从主视图抽出；主视图保留画布事件、浮层定位、上传、项目资源持久化和历史捕获。验证命令：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后未登录刷新弹出 `账号入口`，关闭登录后 `画布背景色` 打开完整 `画布背景设置` 面板，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator` 占位框、`生成图片` 对话框和 `AI画布工具栏` 均可见；登录临时开发账号后上传素材成功，素材数增加，点击素材可加入画布，切换 `图层` 面板可看到对应图层，登录后控制台无前端 error。
+- 2026-06-17 上传鉴权回归修正：普通素材上传入口在未登录时先打开 `账号入口`，不再先弹系统文件选择器；登录后用户再次点击上传即可打开文件选择器，避免浏览器拦截登录后异步触发的系统选择器。拖拽 / 已选中文件的续传逻辑仍保留，角色 / 图标生成参考图仍作为本地引用上传，不强制登录。验证命令：`npm run test -- src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`，`画布背景色` 打开完整 `画布背景设置`，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；未登录点击侧栏上传直接弹登录，不出现文件选择器；登录后再次点击上传可以打开文件选择器并上传成功，素材计数从 4 增至 5，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第十六执行批次：新增 `useImageCanvasEditorChrome`，把项目标题 / 重命名、侧栏开关、当前工具、缩放菜单、背景设置、小地图和背景 HEX 状态从主视图抽出；主视图继续保留上传 / 生成 / 键盘 Escape 的跨工作流编排。新增 hook 单测覆盖重命名、鉴权登录、背景色输入、面板开关和工具状态；主视图从 2039 行降至 1966 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`。
+- 2026-06-17 前端拆分第十七执行批次：新增 `useImageCanvasViewportControls`，把视口状态、画布尺寸、小地图投影、适合视图、中心缩放、滚轮语义、坐标换算和小地图移动从主视图抽出；主视图继续保留图层拖拽、框选、生成占位拖拽、上传 drop 和历史触发时机。验证命令：`npm run test -- src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新弹出 `账号入口`，登录后素材 / 画布 / 小地图和底部工具栏可见；普通滚轮不改变缩放，Ctrl 滚轮从 `100%` 到 `110%`；背景设置点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第十八执行批次：新增 `useImageCanvasStageInteractions`，把画布舞台 pointer 状态机、选择 / 框选、多选拖拽、生成占位拖拽、抓手 / Space 临时抓手 / 中键平移、小地图 click / drag 分流和吸附线状态从主视图抽出；主视图继续保留上传 drop、右键菜单、生成提交、项目持久化和工具栏动作分流。新增 hook 单测覆盖多选拖拽、框选、临时抓手、生成占位和小地图分流；主视图从 1802 行降至 1452 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录刷新和未登录上传均弹出 `账号入口`，登录后素材 / 画布 / 小地图和底部工具栏保持可见；`画布背景设置` 点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；普通滚轮不改变缩放，Ctrl 滚轮从 `146%` 到 `161%`；抓手 / 文字 / 选择工具可连续切换；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，关闭对话框后占位图保留，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第十九执行批次：新增 `useImageCanvasCanvasDropWorkflow`，把画布区域 drag over / drag leave / drop 分流从主视图抽出，覆盖素材库图片拖入画布、本地文件拖入画布、无关拖拽不拦截、默认文件夹选择和画布遮罩清理；主视图继续注入素材建层、文件上传、drop 点换算和素材移动高亮清理。新增 hook 单测覆盖拖拽入画布细节，主视图从 1452 行降至 1405 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 登录态刷新后素材 / 画布 / 小地图和底部工具栏可见，真实鼠标拖拽素材库图片到画布时出现 `添加到画布` 遮罩，松手后画布图层数量从 4 增至 5；`画布背景设置` 点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；抓手工具可切回选择工具，登录后控制台无前端 error。
+- 2026-06-17 前端拆分第二十执行批次：新增 `ImageCanvasMetadataModalView`，把图片信息弹窗从主视图抽出，承载图片类型、生成输入、参考图、模型、分辨率、Provider、Task 和 Object 信息渲染；主视图只保留 `metadataLayer` 状态和关闭回调。同步修复未登录进入编辑器时项目 / 素材接口抢跑 401、`重置画布视图` 点击事件误传给适合视图函数的问题。新增组件单测覆盖生成图 metadata、上传图 fallback 和关闭回调，新增 hook / 主视图测试覆盖未登录不请求受保护素材 / 工程数据和重置按钮回归；主视图从 1405 行降至 1337 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasMetadataModalView.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 清空会话后直接弹出 `账号入口`，且未登录状态下没有发起 `/api/editor/*` 请求；登录临时开发账号后 `重置画布视图` 无控制台错误，`画布背景设置` 保持 Lovart 式白色浮层，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)`，上传素材可加入画布，右上角图片信息按钮可打开不透明白底元数据弹窗，关闭后 `AI画布工具栏` 仍可见。
+- 2026-06-17 前端拆分第二十一执行批次：新增 `useImageCanvasKeyboardShortcuts`，把 Ctrl / Cmd + Z 撤销、Ctrl / Cmd + Shift + Z 重做、Shift 状态、Backspace / Delete 删除、Escape 关闭临时面板和 Space 临时抓手从主视图抽出；主视图继续注入图层删除、生成对话框、快速编辑和 chrome 面板 setter。新增 hook 单测覆盖输入框忽略快捷键、删除选中图层、删除生成占位、Escape 保留生成中面板、Space 和 Shift；主视图从 1337 行降至 1250 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx src/components/image-editor/ImageCanvasMetadataModalView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10003/editor/canvas` 未登录直接弹出 `账号入口` 且未抢跑 `/api/editor/*`，登录后 `/api/editor/assets/library` 和 `/api/editor/projects/recent` 为 200，`AI画布工具栏` 与 `画布面板入口` 可见，viewport 背景为 `rgb(248, 250, 252)` 且 `background-image: none`；按住 Space 从 `文字工具` 临时切到 `抓手工具`，松开恢复 `文字工具`；`画布背景设置` 点击 `暖灰` 后背景变为 `rgb(243, 240, 234)`；点击 `生成工具` 后 `Image Generator` 占位框、`生成图片` 对话框和 `AI画布工具栏` 同时可见，登录后控制台无前端 error。
+- 2026-06-18 生成中占位图删除确认：画布生成占位框增加删除按钮，删除 `generating` 状态占位图时统一弹出 `删除生成中的占位图` 二次确认，并提示 `已消耗的泥点不会返还`；空闲占位仍直接删除。键盘 Backspace / Delete 删除生成占位也改走同一请求入口，避免绕过提示；确认删除后清理选中态、右键菜单并切回选择工具，已删除的生成任务即使后续返回结果也不会落图。验证命令：`npm run test -- src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：本地 Vite + Chrome CDP 打开 `/editor/canvas`，点击 `生成图片` 创建生成中占位，删除按钮弹出确认框，取消后占位保留，确认后占位移除且提示包含泥点不返还。
+- 2026-06-17 前端拆分第二十二执行批次：新增 `useImageCanvasAssetPointerDragBridge`，把素材卡片 pointer 拖拽到画布 / 文件夹的全局监听、拖拽激活、画布 drop 提示、文件夹高亮、移动素材、加入画布和点击抑制从主视图抽出；主视图继续负责素材库事实、画布建层、历史和工程资源持久化。同步恢复 `账号入口` 认证弹窗 portal 渲染，避免全屏画布遮住登录弹窗；`画布背景设置` 调整为独立白色浮层，包含当前色、色域、色相、自定义颜色、预设网格、HEX 输入和恢复默认。验证命令：`npm run test -- src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx src/components/image-editor/ImageCanvasMetadataModalView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/auth/PlatformAuthModalShell.test.tsx src/components/auth/AuthGate.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 未登录打开直接显示 `账号入口`；登录临时开发账号后 `画布背景设置` 显示当前色、色域、色相、自定义颜色、预设、HEX 和恢复默认，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；上传图片进入 `项目素材`，真实 pointer 拖拽素材到画布后图层数从 0 到 1 且 `AI画布工具栏` 保持可见；新建 `SmokeFolder` 后真实 pointer 拖拽素材到文件夹，`项目素材` 变 0、`SmokeFolder` 变 1，素材执行移动而非拷贝。控制台仅有未登录 refresh 401，登录后编辑器 API 均为 200。
+- 2026-06-17 前端拆分第二十三执行批次：新增 `ImageCanvasOverlayModel`，把生成输入框锚定、图标素材生成面板宽度、选中图片工具栏边界、快速编辑面板和角色动画面板定位从主视图抽出为纯模型；主视图继续保留生成 / quick edit / 角色动画状态机和舞台编排。新增模型单测覆盖锚定优先级、生成中隐藏、icon 宽度、工具栏 clamp、quick edit / 角色动画边界和生成 dialog 模式识别；主视图从 1182 行降至 1133 行。验证命令：`npm run test -- src/components/image-editor/ImageCanvasOverlayModel.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run test -- src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasOverlayModel.test.ts src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx src/components/image-editor/ImageCanvasMetadataModalView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasViewportControls.test.tsx src/components/image-editor/ImageCanvasInteractionModel.test.ts src/components/image-editor/useCanvasHistory.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/auth/PlatformAuthModalShell.test.tsx src/components/auth/AuthGate.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 未登录打开显示 `账号入口`，登录后 `画布背景设置` 点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见；素材库已有素材真实 pointer 拖入画布后图层数从 0 到 1，工具栏保持可见，截图留存于 `output/playwright/editor-overlay-model-regression-20260617.png`。
+- 2026-06-17 前端拆分第二十四执行批次：新增 `useImageCanvasAssetCanvasBridge`，把删除素材清理画布图层、素材加入画布、素材 pointer 拖入画布 / 文件夹、画布 drag/drop 分流和文件拖入画布参数组装从主视图抽成素材到画布桥接 hook；主视图继续保留素材库事实、上传读取、工程资源持久化和历史触发。新增 hook 单测覆盖素材建层、pointer drop 入画布和删除素材清理关联图层 / 选中态；主视图从 1133 行降至 1086 行。验证命令：`npm run test -- src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 清空会话后未登录直接显示 `账号入口`；登录临时开发账号后 `画布背景设置` 是完整设置面板，包含当前色、色域、色相、自定义颜色、预设、HEX 和恢复默认，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，HEX 输入 `#ffffff` 后变为白色，按 Escape 关闭面板；登录后上传图片请求 `/api/editor/assets` 返回 200，素材库出现上传素材，`AI画布工具栏` 保持可见。
+- 2026-06-17 前端拆分第二十五执行批次：新增 `ImageCanvasStageControllerModel` 和 `useImageCanvasStageController`，把舞台派生状态、生成 / 选中浮层位置、右键菜单目标、空白画布右键、图层右键和清空画布焦点从主视图抽出；主视图继续保留工具切换、上传 / 生成入口、图层命令、项目持久化和舞台 pointer 状态机。新增模型和 hook 单测覆盖选中 / 生成锚定、右键菜单位置、显示 / 解锁判断、清空焦点和空白 / 图层右键菜单；主视图从 1086 行降至 993 行。验证命令：`npm run test -- src/components/image-editor/ImageCanvasStageControllerModel.test.ts src/components/image-editor/useImageCanvasStageController.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/routing/appPageRoutes.test.ts`、`npm run typecheck`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 清空会话后未登录直接显示 `账号入口`，关闭登录后 `画布背景色` 打开完整 `画布背景设置` dialog，包含色相、自定义颜色、预设、HEX 和恢复默认；点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，`AI画布工具栏` 保持可见，截图留存于 `output/playwright/editor-stage-controller-smoke-20260617.png`。
+- 2026-06-17 前端拆分第二十六执行批次：新增 `ImageCanvasTopbarView`，把返回项目入口、项目标题展示 / 重命名表单、下载画布素材按钮和导出状态提示从主视图抽出；主视图继续保留 chrome hook、项目持久化、导出工作流和实际导出副作用。新增组件单测覆盖返回入口、标题编辑入口、重命名提交 / 取消、导出按钮禁用 / 启用和导出状态提示；主视图从 993 行降至 905 行。验证命令：`npm run test -- src/components/image-editor/ImageCanvasTopbarView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/useImageCanvasAssetExportWorkflow.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 未登录直接显示 `账号入口`，顶栏返回项目入口、项目名、`画布` 标签和下载按钮均可见；关闭登录后打开 `画布背景设置`，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，`AI画布工具栏` 保持可见，截图留存于 `output/playwright/editor-topbar-smoke-20260617.png`。
+- 2026-06-17 前端拆分第二十七执行批次：新增 `useImageCanvasGenerationSurface`，把生成 Composer JSX、生成工具切换分流、普通生图 / 图标生成 / 快速编辑 / 角色动画浮层定位从主视图抽出；`useImageCanvasGenerationWorkflow` 继续负责生成状态机和真实 API 提交。同步移除 `ImageCanvasStageControllerModel` 中重复的生成锚点 / Composer 位置派生，避免舞台控制器和生成表面重复持有生成浮层职责；主视图从 905 行降至 793 行。rebase 到远端 `支持规范参考图输入` 后，生成表面继续透传角色形象规范和常规参考图入口，并把左下 dock / 底部工具栏层级提到 Composer 之上，避免生成输入框盖住常用工具和背景面板。验证命令：`npm run test -- src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/ImageCanvasStageControllerModel.test.ts src/components/image-editor/useImageCanvasStageController.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 未登录直接显示 `账号入口`，关闭登录后 `画布背景设置` 保持完整面板，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，再点击 `生成角色形象` 能打开包含 `角色形象规范` 和 `常规参考图` 的对话框，控制台仅有未登录 refresh 401。
+- 2026-06-17 上传侧栏回归修正：上传工作流移除上传到画布后强制切换 `图层` 侧栏的副作用，保留新增素材卡、创建画布图层和选中新图层。验证命令：`npm run test -- src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 登录后点击 `上传到项目素材` 上传图片，左侧仍显示 `素材` 且 `打开素材` 为 pressed；把图片文件 drop 到 `画布工作区` 后素材库和画布图层均出现 `canvas-drop-sidebar-smoke.png`，新图层被选中，`打开素材=true`、`打开图层=false`，`AI画布工具栏` 保持可见，登录后控制台无 error。
+- 2026-06-17 前端拆分第二十八执行批次：继续收口 `ImageCanvasGenerationComposerView`，新增 `ImageCanvasGenerationImageOptionsView`、`ImageCanvasSpecGenerationPanelView`、`ImageCanvasIconSpritesheetComposerView`、`ImageCanvasQuickEditPanelView` 和 `ImageCanvasCharacterAnimationPanelView`，把图片生成参数、生成规范、图标素材生成、快速编辑图片和角色动画面板从 Composer 内联 JSX 抽出；Composer 降至 707 行，继续保留生成模式分流、角色引用菜单 portal 和修改图片弹窗编排。新增子视图单测覆盖参数切换、规范表单、图标规范菜单 / 描述列表、快速编辑和角色动画状态。验证命令：`npm run test -- src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 未登录显示 `账号入口`，关闭后点击 `生成工具` 能看到 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏`；点击 `生成角色形象` 能看到 `生成角色形象` 面板和 `角色形象规范`；点击 `生成规范` 后选择 `角色形象规范` 能打开 `生成规范` 面板并显示 `提交生成规范`；点击 `生成图标素材` 能打开 `生成图标素材` 面板、图标规范操作和素材描述列表，控制台仅有未登录 refresh 401。
+- 2026-06-17 前端拆分第二十九执行批次：继续收口 `ImageCanvasStageView`，新增 `ImageCanvasBottomToolbarView`、`ImageCanvasPanelDockView`、`ImageCanvasContextMenusView` 和 `ImageCanvasSelectedLayerToolbarView`，把底部 AI 工具栏、左下缩放 / 背景 / 小地图控制坞、画布 / 图片右键菜单和选中图片浮动工具栏从 StageView 内联 JSX 抽出；StageView 降至 538 行，继续保留画布世界、图层和生成占位渲染，所有 pointer / 多选 / 拖拽 / 生成状态机仍在既有 hook 中。新增子视图单测覆盖工具切换、缩放 / 背景 / 小地图控制、右键菜单命令和选中图片工具栏接线。验证命令：`npm run test -- src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录弹出 `账号入口`，关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框、`画布面板入口` 和 `AI画布工具栏` 均可见；点击 `生成规范` 后页面级 `生成规范类型` 菜单可见。控制台仅有预期的未登录 `/api/auth/refresh` 401，截图留存于 `output/playwright/editor-stage-view-split-smoke-20260617.png`。
+- 2026-06-17 前端拆分第三十执行批次：新增 `ImageCanvasEditorShellView`，把编辑器最外层 section、隐藏上传 input、素材拖拽预览、侧栏 / 顶栏 / 舞台 / 元数据弹窗组合从 `ImageCanvasEditorView` 抽成页面壳；主视图继续保留所有 hook 状态编排、上传 / 生成 / 拖拽 / 项目持久化和跨模块副作用，只把已经组装好的 `sidebarProps`、`topbarProps`、`stageProps` 和 `metadataProps` 交给 shell 渲染。新增 shell 单测覆盖上传 input、拖拽预览坐标兜底、顶栏 / 舞台 / 工具栏 / 元数据弹窗装配；主视图降至 777 行。验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`，关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`返回项目页面`、`画布面板入口` 和 `AI画布工具栏` 均可见；点击 `生成工具` 后 `Image Generator` 和 `生成图片` 对话框可见；点击 `生成规范` 后页面级 `生成规范类型` 菜单可见。控制台仅有预期的未登录 `/api/auth/refresh` 401，截图留存于 `output/playwright/editor-shell-split-smoke-20260617.png`。
+- 2026-06-17 前端拆分第三十一执行批次：继续收口 `ImageCanvasSidebarView`，新增 `ImageCanvasAssetLibraryPanelView` 和 `ImageCanvasLayerPanelView`，把素材库文件夹 / 拖拽上传 / 素材选择模式与图层列表 / 右键入口拆成两个完整 surface；侧栏外壳只保留标题、计数和当前 tab 分流。同步把 `ImageCanvasEditorView.test.tsx` 中纯侧栏输入框 chrome 断言迁到 `ImageCanvasSidebarView.test.tsx`，保留主视图重命名、建文件夹、上传、删除、API 调用和画布集成断言。验证命令：`npm run test -- src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/useImageCanvasEditorChrome.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "switches the shared sidebar between assets and layers"`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 2026-06-17 前端拆分第三十二执行批次：继续收口 `ImageCanvasGenerationComposerView`，新增 `ImageCanvasBasicGenerationComposerView`、`ImageCanvasCharacterGenerationComposerView` 和 `ImageCanvasEditGenerationModalView`，把普通生图跟随框、角色形象生成面板和修改图片弹窗从 Composer 内联 JSX 中抽出；Composer 降至 312 行，只保留生成模式分流、portal 菜单和各面板装配。新增三组子视图单测覆盖普通生图 prompt / 参考图 / 提交 / 关闭、角色参考图菜单 / 状态恢复 / 提交、修改图片弹窗提示词 / 失败 / 关闭。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口` 且控制台仅有预期 `/api/auth/refresh` 401；关闭登录后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏显示 `图层`，`AI画布工具栏` 仍可见；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和底部工具栏均可见。
+- 2026-06-17 前端拆分第三十三执行批次：继续收口 `ImageCanvasAssetLibraryPanelView`，新增 `ImageCanvasAssetFolderSectionView` 和 `ImageCanvasAssetRowView`，把素材库文件夹头 / 文件夹 drop 区域、素材卡片 / 上传进度 / 重命名 / 选择模式从素材库父面板中拆成两个完整 surface；素材库父面板降至 279 行，只保留素材列表容器、新建文件夹表单、批量操作栏和框选遮罩。新增素材行单测覆盖普通点击加入画布、选择模式改为选中、重命名 Enter 提交和上传中禁用 / 进度显示。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口` 且控制台仅有预期 `/api/auth/refresh` 401；默认素材栏显示 `项目素材` 文件夹、上传入口和底部 `AI画布工具栏`；关闭登录后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏显示 `图层`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和底部工具栏均可见。
+- 2026-06-17 前端拆分第三十四执行批次：继续收口 `ImageCanvasStageView`，新增 `ImageCanvasWorldView`，把画布世界表面、吸附参考线、可见图层排序 / 悬浮 / 选中 / 锁定 / 生成态、元数据角标、框选矩形、生成占位框和浮动生成状态从 StageView 内联 JSX 中抽出；StageView 降至 324 行，继续保留 viewport 宿主、drop overlay、左下 dock、底部工具栏、右键菜单和选中图片工具栏装配。新增 world view 单测覆盖隐藏图层过滤、悬浮尺寸、生成态、元数据按钮、吸附线、框选矩形和生成占位框事件。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasWorldView.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`，`AI画布工具栏` 保持可见；`打开图层` 切换后侧栏显示 `图层`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和底部工具栏均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第三十五执行批次：继续收口 `useImageCanvasGenerationWorkflow`，新增 `ImageCanvasGenerationSubmissionModel`，把普通生图、修改图片、规范生成和角色形象生成的请求 payload、标准化 prompt、结果图层标题 / assetKind 和 generationInputs 快照构建从 workflow hook 中抽成纯模型；workflow hook 保留对话状态、真实 API 调用、图片引用解析、结果落图、选中和 fit 副作用，避免拆散生成生命周期。新增模型单测覆盖普通生图、修改图、带参考图的规范生成、带规范 / 常规参考图的角色生成和缺失源图异常；`useImageCanvasGenerationWorkflow` 从 1167 行降至 1104 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第三十六执行批次：继续收口 `useImageCanvasUploadWorkflow`，新增 `ImageCanvasUploadModel`，把上传目标文件夹解析、上传中素材占位卡、上传到画布的临时图层、无效 drop 坐标兜底和图片真实尺寸回填坐标计算从 hook 中抽成纯模型；upload workflow hook 保留登录恢复、文件读取、真实素材创建 API、上传进度状态和生成面板参考图写入副作用。新增模型单测覆盖文件夹兜底、占位素材、画布落点、非法坐标兜底和真实尺寸修正；`useImageCanvasUploadWorkflow` 从 546 行降至 510 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框、`上传到项目素材` 入口和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第三十七执行批次：继续收口 `useImageCanvasAssetLibrary`，新增 `ImageCanvasAssetLibraryModel`，把素材分组、可选择素材筛选、全选状态、素材 / 文件夹重命名、文件夹折叠、本地新建文件夹占位、持久化文件夹替换、本地删除素材、删除文件夹回默认文件夹、选择集合切换、批量删除和本地移动素材到文件夹从 hook 中抽成纯模型；asset library hook 继续保留加载账号素材库、后端 CRUD 调用、登录弹窗、DOM 框选和素材拖拽命中生命周期。新增模型单测覆盖分组 / 选择、重命名 / 折叠 / 本地文件夹、本地文件夹持久化替换、删除文件夹回默认文件夹、全选 / 批量删除和本地移动；`useImageCanvasAssetLibrary` 从 609 行降至 573 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/useImageCanvasAssetLibrary.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏显示 `图层`，点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见；切回 `打开素材` 后侧栏显示 `素材` 且 `上传到项目素材` 入口可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第三十八执行批次：继续收口 `useImageCanvasGenerationWorkflow`，扩展 `ImageCanvasGenerationSubmissionModel`，把图标素材批量生成的规范校验 / 描述清洗 / 请求 payload / generationInputs，以及角色动画生成的 prompt 清洗 / objectKey 优先源图 / 尺寸 / 价格 / 模型参数从 workflow hook 中抽成纯模型；workflow hook 继续保留对话状态、真实 API 调用、生成结果落图、失败恢复和角色动画面板生命周期。新增模型单测覆盖图标缺少规范、图标空描述、图标描述 trim / 参考快照，以及角色动画 trim、objectKey 源图和价格计算；`useImageCanvasGenerationWorkflow` 从 1104 行降至 1075 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏显示 `图层`，点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见；点击 `生成图标素材` 后 `Icon Generator` 占位和 `生成图标素材` 面板可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第三十九执行批次：开始拆分 `ImageCanvasEditorView.test.tsx` 巨型集成测试，新增 `ImageCanvasEditorView.test-utils` 共享默认工程 / 素材库 mock、认证上下文、pointer / dataTransfer / deferred helper 和生命周期 setup；新增 `ImageCanvasEditorAssetsIntegration.test.tsx`，把素材库默认文件夹去重、文件夹折叠 / 新建 / 重命名 / 删除、素材重命名 / 拖拽移动、多文件上传、未登录续传、上传占位、401 登录、素材选择模式、删除素材同步清理画布图层、素材框选、画布 drop 上传和素材库拖入画布等集成用例从主测试文件迁出；`ImageCanvasEditorView.test.tsx` 从 4817 行降至 3741 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏显示 `图层`，点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第四十执行批次：继续拆分 `ImageCanvasEditorView.test.tsx` 巨型集成测试，新增 `ImageCanvasEditorGenerationIntegration.test.tsx`，把画布生图占位 / 生成提交、生成错误与未登录、规范生成、角色形象生成、图标素材生成、角色动画、快速编辑、生成图元数据和修改结果等生成相关集成用例从主测试文件迁出；`ImageCanvasEditorView.test.tsx` 从 3741 行降至 1419 行，主测试保留工程加载、导出、画布基础交互、右键菜单、侧栏、缩放、小地图、工具切换、吸附和历史。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏标题为 `图层`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第四十一执行批次：继续收口 `useImageCanvasGenerationWorkflow`，新增 `ImageCanvasGenerationDialogModel`，把普通生图 / 规范 / 角色形象 / 图标素材生成对话框草稿、修改图片 / 快速编辑 / 角色动画面板草稿、角色 / 图标参考选择、规范表单更新、图标描述更新、角色动画时长更新以及生成器失焦 / 关闭规则从 hook 中抽成纯模型；workflow hook 保留真实 API 调用、生成结果落画布、侧栏 / 工具 / 选中态副作用和错误回写。新增模型单测覆盖各类草稿、失败态清理、引用选择、描述限制、动画时长和 composer 可见性；`useImageCanvasGenerationWorkflow.ts` 从 1075 行降至 870 行。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏标题为 `图层`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第四十二执行批次：继续收口 `useImageCanvasStageInteractions`，新增 `ImageCanvasStageInteractionModel`，把 pointer button / client / id 归一化、画布框选初始状态、抓手平移拖拽状态、多选图层选择与图层拖拽初始状态、生成器 composer 随图层点击显隐、生成占位拖拽状态、小地图拖拽状态和拖拽阈值从 hook 中抽成纯模型；stage hook 保留 DOM 事件拦截、pointer capture / release、React 状态写入、拖拽移动执行和回调副作用。新增模型单测覆盖 pointer 兜底、中键识别、框选 / 平移状态、多选 toggle、组拖拽初始层快照、生成器 composer 规则、生成占位状态和小地图 click / drag 分流；`useImageCanvasStageInteractions.ts` 从 610 行降至 521 行。只读子代理复核结论：当前没有同一轮必须顺手拆的第二个明显大块，`ImageCanvasEditorView.tsx` 已主要是组合层，generation / asset / upload hooks 剩余复杂度多为异步编排或持久化副作用，后续应随具体需求再拆，避免过度碎片化。统一验证命令：`npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/useImageCanvasStageInteractions.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；`打开图层` 切换后侧栏标题为 `图层`；点击 `生成工具` 后 `Image Generator`、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第四十三执行批次：继续收口 `useImageCanvasGenerationWorkflow`，新增 `useImageCanvasGenerationSubmissionWorkflow`，把普通生图 / 修改图 / 图标素材批量生成 / 快速编辑 / 角色动画的提交 API、提交中 / 失败 / 完成状态回写、生成结果落画布、选中图层、切换图层侧栏、适合视图和 last image model 记忆从入口 workflow 中抽成生成提交流水线 hook；原 workflow 保留生成入口、菜单开关、画布选取引用、表单字段更新、生成器关闭和删除图层后的状态清理，避免把 UI 选择态和提交态混在一起。新增 hook 单测覆盖 quick edit 成功 / 失败、edit 成功清理 modal、生成使用最新移动占位、icon 缺规范校验、icon 成功批量落图并记住模型、角色动画 completed / failed 状态机；同步修复新测试文件的 mock 隔离，避免 `vi.clearAllMocks()` 清空并行集成测试的调用记录；`useImageCanvasGenerationWorkflow.ts` 从 870 行降至 499 行。统一验证命令：`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`、`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`；浏览器回归：`http://127.0.0.1:10007/editor/canvas` 临时 `XDG_CONFIG_HOME` 下 Chrome headless 打开成功，未登录显示 `账号入口`；关闭后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；点击 `生成工具` 后 `Image Generator` 占位、`生成图片` 对话框和 `AI画布工具栏` 均可见，控制台仅有预期的未登录 `/api/auth/refresh` 401。
+- 2026-06-17 前端拆分第四十四执行批次：继续收口 `useImageCanvasAssetLibrary`，扩展 `ImageCanvasAssetLibraryModel`，把素材文件夹坐标命中、素材拖拽目标文件夹置顶判断、素材框选起点 / 移动 / 反向拖拽矩形归一化、框选只命中 uploaded 素材和框选启动规则从 hook 中抽成纯几何模型；asset library hook 保留 DOM 查询、dataset 读取、pointer capture / release、React 状态写入、后端 CRUD 和登录弹窗副作用，避免把 DOM 与服务调用塞进模型。新增模型单测覆盖文件夹边界命中、列表外返回空、文件夹 header 视野外置顶、反向框选归一化、边缘相交命中、忽略 built-in / unknown 素材；只读子代理复核同意优先抽 Rect/Point + folder hit + pinned + marquee selection，不继续拆新 hook。验证命令：`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/useImageCanvasAssetLibrary.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`。
+- 2026-06-17 前端拆分第四十四执行批次验证补充：统一编辑器回归命令 `npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx` 通过 33 个文件 / 219 个测试；`npm run typecheck`、`npm run check:encoding`、`git diff --check` 均通过。浏览器回归：`http://127.0.0.1:10007/editor/canvas` 使用 Playwright CLI headless 打开成功，未登录显示 `账号入口`；关闭登录后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；默认素材侧栏显示 `素材` / `项目素材` / `上传到项目素材`，切换 `打开图层` 后侧栏显示 `图层`，点击 `生成工具` 后 `Image Generator` 占位、`生成图片` 对话框和 `AI画布工具栏` 均可见；网络请求仅有预期未登录 `/api/auth/refresh` 401，其余 editor smoke 相关请求正常。
+- 2026-06-17 前端拆分第四十五执行批次：继续收口 `useImageCanvasUploadWorkflow`，扩展 `ImageCanvasUploadModel`，把生成参考图上传后的 dialog 状态转换从 hook 中抽成纯模型：统一创建上传参考图对象、将 failed 生成面板恢复为 idle、按 `spec-reference` / `character-spec` / `character-reference` / `icon-spec` 写入对应引用字段，并保持不匹配 dialog 不变；upload workflow hook 继续保留文件筛选、Data URL 读取、文件 input、未登录素材上传续传、真实素材创建 API、上传进度和画布落图副作用。新增模型单测覆盖参考图 fallback label、failed 状态清理、规范 / 角色 / 图标参考图写入和角色参考图追加；局部验证命令：`npm run test -- src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx`。
+- 2026-06-17 前端拆分第四十五执行批次验证补充：统一编辑器回归命令 `npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx` 通过 33 个文件 / 223 个测试；`npm run typecheck`、`npm run check:encoding`、`git diff --check` 均通过。浏览器回归：`http://127.0.0.1:10007/editor/canvas` 使用 Playwright CLI headless 打开成功，未登录显示 `账号入口`；关闭登录后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；默认素材侧栏显示 `素材` / `项目素材` / `上传到项目素材`，切换 `打开图层` 后侧栏显示 `图层`，点击 `生成工具` 后 `Image Generator` 占位、`生成图片` 对话框和 `AI画布工具栏` 均可见；网络请求仅有预期未登录 `/api/auth/refresh` 401，其余 editor smoke 相关请求正常。只读子代理复核生成提交链路后建议暂停继续硬拆，除非后续新增生成模式再考虑按“生成成功后的落图提交事务”抽内部 hook。
+- 2026-06-17 前端拆分第四十六执行批次：继续收口 `useImageCanvasUploadWorkflow`，扩展 `ImageCanvasUploadModel`，把素材上传生命周期中的文件夹展开、读取成功 / 失败、上传中、持久化资产替换、上传失败、图片尺寸回写和画布图层绑定持久化素材抽成纯模型；upload workflow hook 继续保留文件筛选、Data URL 读取、登录弹窗、真实素材创建 API、Image 尺寸读取、画布落图和 React setter 编排。新增模型单测覆盖上传占位卡各阶段状态、持久化后清理上传态、尺寸回写和图层绑定；局部验证命令：`npm run test -- src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx`。
+- 2026-06-17 前端拆分第四十六执行批次验证补充：统一编辑器回归命令 `npm run test -- src/components/image-editor/ImageCanvasStageInteractionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/image-editor/ImageCanvasSidebarView.test.tsx src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx src/components/image-editor/ImageCanvasEditorShellView.test.tsx src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/ImageCanvasPanelDockView.test.tsx src/components/image-editor/ImageCanvasContextMenusView.test.tsx src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/useImageCanvasAssetLibrary.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/useImageCanvasStageInteractions.test.tsx src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx` 通过 33 个文件 / 228 个测试；`npm run typecheck`、`npm run check:encoding`、`git diff --check` 均通过。浏览器回归：`http://127.0.0.1:10007/editor/canvas` 使用系统 Chrome headless 打开成功，未登录显示 `账号入口`；默认素材侧栏显示 `素材` / `项目素材`；关闭登录后 `画布背景设置` 可打开，点击 `暖灰` 后 viewport 背景为 `rgb(243, 240, 234)` 且 `background-image: none`；切换 `打开图层` 后侧栏显示 `图层`；点击 `生成工具` 后 `Image Generator` 占位、生成表单控件和 `AI画布工具栏` 均可见；除预期未登录 `/api/auth/refresh` 401 外无额外 API 失败或控制台错误。
diff --git a/docs/README.md b/docs/README.md
index acbd05333..dc5caf067 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,12 @@
 
 微信小程序虚拟支付接入、`wechat_mp_virtual` 渠道、`wx.requestVirtualPayment` 承接页和后端签名配置见 [【技术方案】微信虚拟支付接入-2026-05-26.md](./%E3%80%90%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88%E3%80%91%E5%BE%AE%E4%BF%A1%E8%99%9A%E6%8B%9F%E6%94%AF%E4%BB%98%E6%8E%A5%E5%85%A5-2026-05-26.md)。
 
+`/editor/agent` 浏览器内 AI Web 工程编辑器的静态 SPA 沙箱预览 MVP，采用“平台编辑器壳 + api-server 控制面 + 独立 runner worker + 独立预览域”四层结构；技术方案、威胁模型和验收清单见 [【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md](./technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md)、[【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md](./technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md) 和 [【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md](./technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md)。P1 先用确定性 mock Agent 生成结构化 patch、真实打通项目 / 快照 / 构建 / artifact / 预览闭环，落地拆分见 [【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md](./technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md)。
+
+`/editor/canvas` 图片画布编辑器的画布素材 ZIP 导出能力，入口放在右上角标题栏下载图标内，第一版采用前端 JSZip 打包画布中有效图层引用的上传图、生成图和修改结果，方案见 [【前端架构】图片画布素材导出方案-2026-06-15.md](./technical/【前端架构】图片画布素材导出方案-2026-06-15.md)。
+
+桌面端 `/creation` 创作工具主页、顶级“草稿”入口替换为“项目”、最近项目、新建项目和陶泥儿精选素材瀑布流的落地计划见 [【玩法创作】创作主页与项目入口改版计划-2026-06-18.md](./%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E5%88%9B%E4%BD%9C%E4%B8%BB%E9%A1%B5%E4%B8%8E%E9%A1%B9%E7%9B%AE%E5%85%A5%E5%8F%A3%E6%94%B9%E7%89%88%E8%AE%A1%E5%88%92-2026-06-18.md)。
+
 本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
 
 生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。Pingora 只作为独立二进制影子网关试点时，边界、路由口径与替换前验收见 [【开发运维】Pingora独立网关试点-2026-06-11.md](./technical/【开发运维】Pingora独立网关试点-2026-06-11.md)。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
diff --git a/docs/openapi/genarrative-external-v1.openapi.json b/docs/openapi/genarrative-external-v1.openapi.json
new file mode 100644
index 000000000..bf7087e02
--- /dev/null
+++ b/docs/openapi/genarrative-external-v1.openapi.json
@@ -0,0 +1,3461 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "陶泥儿外部编辑器 OpenAPI",
+    "version": "1.0.0",
+    "description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库，以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。"
+  },
+  "servers": [
+    {
+      "url": "/",
+      "description": "当前部署环境"
+    }
+  ],
+  "tags": [
+    {
+      "name": "Editor Projects",
+      "description": "图片画布项目"
+    },
+    {
+      "name": "Editor Canvas",
+      "description": "图片画布布局"
+    },
+    {
+      "name": "Editor Assets",
+      "description": "账号级编辑器素材库"
+    },
+    {
+      "name": "Asset Objects",
+      "description": "素材对象上传、确认与签名读取"
+    },
+    {
+      "name": "Editor Images",
+      "description": "编辑器美术生图"
+    },
+    {
+      "name": "Editor Videos",
+      "description": "编辑器视频与角色动画生成"
+    },
+    {
+      "name": "Editor Audio",
+      "description": "编辑器音效与音乐生成"
+    }
+  ],
+  "paths": {
+    "/api/external/v1/openapi.json": {
+      "get": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "getExternalOpenApiJson",
+        "summary": "读取外部 API OpenAPI JSON",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "OpenAPI 3.1 JSON",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/external/v1/assets/direct-upload-tickets": {
+      "post": {
+        "tags": [
+          "Asset Objects"
+        ],
+        "operationId": "createExternalDirectUploadTicket",
+        "summary": "创建素材直传 OSS 凭证",
+        "description": "为外部编辑器素材上传创建一次性 OSS 表单直传参数。上传完成后应调用 objects/confirm 确认 asset object，再创建素材记录。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateDirectUploadTicketRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "直传凭证",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateDirectUploadTicketResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/assets/objects/confirm": {
+      "post": {
+        "tags": [
+          "Asset Objects"
+        ],
+        "operationId": "confirmExternalAssetObject",
+        "summary": "确认素材对象",
+        "description": "确认已上传的 OSS 对象并写入 asset_object；ownerUserId 固定使用 API Key 所属账号，请求体中的 ownerUserId 会被忽略。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConfirmAssetObjectRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "素材对象记录",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConfirmAssetObjectResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/assets/read-url": {
+      "get": {
+        "tags": [
+          "Asset Objects"
+        ],
+        "operationId": "getExternalAssetReadUrl",
+        "summary": "获取私有素材读取签名 URL",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "objectKey",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "legacyPublicPath",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "expireSeconds",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "签名读取 URL",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetAssetReadUrlResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects": {
+      "get": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "listEditorProjects",
+        "summary": "列出当前账号图片画布项目",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "项目列表",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "createEditorProject",
+        "summary": "创建图片画布项目",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorProjectCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已创建项目",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects/recent": {
+      "get": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "loadRecentEditorProject",
+        "summary": "读取当前账号最近图片画布项目",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "最近项目；当前账号没有项目时 project 为 null",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectRecentResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects/{projectId}": {
+      "get": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "getEditorProject",
+        "summary": "读取图片画布项目",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "项目快照",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "deleteEditorProject",
+        "summary": "删除图片画布项目",
+        "description": "删除项目时级联清理默认画布与项目资源元数据。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "已删除项目",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectDeleteResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects/{projectId}/metadata": {
+      "patch": {
+        "tags": [
+          "Editor Projects"
+        ],
+        "operationId": "renameEditorProject",
+        "summary": "更新图片画布项目标题",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorProjectRenameRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "更新后的项目快照",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects/{projectId}/canvas": {
+      "patch": {
+        "tags": [
+          "Editor Canvas"
+        ],
+        "operationId": "saveEditorProjectCanvas",
+        "summary": "保存默认画布布局",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorCanvasSaveRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "保存后的项目快照",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/projects/{projectId}/resources": {
+      "post": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "createEditorProjectResource",
+        "summary": "创建项目画布资源记录",
+        "description": "把上传、生成或外部已有图片资源写入指定项目的画布资源表，供画布图层引用。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorProjectResourceCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已创建项目画布资源",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorProjectResourceResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/assets/library": {
+      "get": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "getEditorAssetLibrary",
+        "summary": "读取当前账号编辑器素材库",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "素材库快照",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetLibraryResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/assets/folders": {
+      "post": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "createEditorAssetFolder",
+        "summary": "创建素材文件夹",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorAssetFolderCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已创建素材文件夹",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetFolderResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/assets/folders/{folderId}": {
+      "patch": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "updateEditorAssetFolder",
+        "summary": "更新素材文件夹",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/FolderId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorAssetFolderUpdateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已更新素材文件夹",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetFolderResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "deleteEditorAssetFolder",
+        "summary": "删除素材文件夹",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/FolderId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "删除后的素材库快照",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetFolderDeleteResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/assets": {
+      "post": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "createEditorAsset",
+        "summary": "创建素材记录",
+        "description": "创建账号级编辑器素材记录。图片二进制上传仍应先通过已有资产上传链路完成，随后在这里保存素材元数据。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorAssetCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已创建素材",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/assets/{assetId}": {
+      "patch": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "updateEditorAsset",
+        "summary": "更新素材名称或所在文件夹",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AssetId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExternalEditorAssetUpdateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "已更新素材",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Editor Assets"
+        ],
+        "operationId": "deleteEditorAsset",
+        "summary": "删除素材记录",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AssetId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "已删除素材",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/images/generations": {
+      "post": {
+        "tags": [
+          "Editor Images"
+        ],
+        "operationId": "generateExternalEditorImage",
+        "summary": "生成编辑器图片素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorImageGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "生成结果与落库资源",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorImageGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        },
+        "description": "支持普通生图、规范图、角色图、快速编辑参考图、UI 设计图和宣发素材生成。kind 可取 spec、character、quick-edit、ui-design、publication-material。"
+      }
+    },
+    "/api/external/v1/editor/images/edits": {
+      "post": {
+        "tags": [
+          "Editor Images"
+        ],
+        "operationId": "editExternalEditorImage",
+        "summary": "重绘/调整编辑器图片素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorImageEditRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "重绘结果与落库资源",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorImageGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/icon-spritesheets/generations": {
+      "post": {
+        "tags": [
+          "Editor Images"
+        ],
+        "operationId": "generateExternalEditorIconSpritesheet",
+        "summary": "按规范图生成并拆分图标素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorIconSpritesheetGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "图标 spritesheet、切片结果与落库资源",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorIconSpritesheetGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/ui-designs/assets/extractions": {
+      "post": {
+        "tags": [
+          "Editor Images"
+        ],
+        "operationId": "extractExternalEditorUiDesignAssets",
+        "summary": "从 UI 设计图拆分素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorUiDesignAssetExtractionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "UI 设计图素材 spritesheet、切片结果与落库资源",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorIconSpritesheetGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/character-animations/generations": {
+      "post": {
+        "tags": [
+          "Editor Videos"
+        ],
+        "operationId": "generateExternalEditorCharacterAnimation",
+        "summary": "生成编辑器角色动画帧",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorCharacterAnimationGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "角色动画视频预览与抽帧结果",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorCharacterAnimationGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/videos/generations": {
+      "post": {
+        "tags": [
+          "Editor Videos"
+        ],
+        "operationId": "generateExternalEditorVideo",
+        "summary": "生成编辑器视频素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorVideoGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "视频生成结果",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorVideoGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/audios/sound-effects/generations": {
+      "post": {
+        "tags": [
+          "Editor Audio"
+        ],
+        "operationId": "generateExternalEditorSoundEffect",
+        "summary": "生成编辑器音效素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorSoundEffectGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "音效生成结果",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorAudioGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    },
+    "/api/external/v1/editor/audios/background-music/generations": {
+      "post": {
+        "tags": [
+          "Editor Audio"
+        ],
+        "operationId": "generateExternalEditorBackgroundMusic",
+        "summary": "生成编辑器背景音乐素材",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EditorBackgroundMusicGenerationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "背景音乐生成结果",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EditorAudioGenerationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "502": {
+            "$ref": "#/components/responses/UpstreamError"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ExternalApiKey": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "tnr_sk"
+      }
+    },
+    "parameters": {
+      "ProjectId": {
+        "name": "projectId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      },
+      "FolderId": {
+        "name": "folderId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      },
+      "AssetId": {
+        "name": "assetId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "请求参数不合法",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "未授权访问",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "禁止访问",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "资源不存在",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
+      "UpstreamError": {
+        "description": "上游生成服务失败",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "ExternalEditorProjectCreateRequest": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "maxLength": 80
+          }
+        },
+        "additionalProperties": false
+      },
+      "CreateDirectUploadTicketRequest": {
+        "type": "object",
+        "required": [
+          "legacyPrefix",
+          "fileName"
+        ],
+        "properties": {
+          "legacyPrefix": {
+            "type": "string",
+            "description": "历史资源前缀，例如 generated-character-drafts。"
+          },
+          "pathSegments": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "fileName": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "access": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "enum": [
+              "public",
+              "private",
+              null
+            ],
+            "default": "private"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "maxSizeBytes": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1
+          },
+          "expireSeconds": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1
+          },
+          "successActionStatus": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "enum": [
+              200,
+              201,
+              204,
+              null
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "CreateDirectUploadTicketResponse": {
+        "type": "object",
+        "required": [
+          "upload"
+        ],
+        "properties": {
+          "upload": {
+            "$ref": "#/components/schemas/DirectUploadTicket"
+          }
+        }
+      },
+      "DirectUploadTicket": {
+        "type": "object",
+        "required": [
+          "signatureVersion",
+          "provider",
+          "bucket",
+          "endpoint",
+          "host",
+          "objectKey",
+          "legacyPublicPath",
+          "access",
+          "keyPrefix",
+          "expiresAt",
+          "maxSizeBytes",
+          "successActionStatus",
+          "formFields"
+        ],
+        "properties": {
+          "signatureVersion": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "bucket": {
+            "type": "string"
+          },
+          "endpoint": {
+            "type": "string"
+          },
+          "host": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": "string"
+          },
+          "legacyPublicPath": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "access": {
+            "type": "string",
+            "enum": [
+              "public",
+              "private"
+            ]
+          },
+          "keyPrefix": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "maxSizeBytes": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "successActionStatus": {
+            "type": "integer"
+          },
+          "formFields": {
+            "type": "object",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      },
+      "ConfirmAssetObjectRequest": {
+        "type": "object",
+        "required": [
+          "objectKey",
+          "assetKind"
+        ],
+        "properties": {
+          "bucket": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "objectKey": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "contentLength": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 0
+          },
+          "contentHash": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": "string"
+          },
+          "accessPolicy": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "enum": [
+              "private",
+              "public_read",
+              null
+            ],
+            "default": "private"
+          },
+          "sourceJobId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ownerUserId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "deprecated": true,
+            "description": "外部接口会忽略该字段并使用 API Key 所属账号。"
+          },
+          "profileId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "entityId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "ConfirmAssetObjectResponse": {
+        "type": "object",
+        "required": [
+          "assetObject"
+        ],
+        "properties": {
+          "assetObject": {
+            "$ref": "#/components/schemas/AssetObject"
+          }
+        }
+      },
+      "AssetObject": {
+        "type": "object",
+        "required": [
+          "assetObjectId",
+          "bucket",
+          "objectKey",
+          "accessPolicy",
+          "contentLength",
+          "version",
+          "assetKind",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "assetObjectId": {
+            "type": "string"
+          },
+          "bucket": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": "string"
+          },
+          "accessPolicy": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "contentLength": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "contentHash": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "version": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceJobId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ownerUserId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "profileId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "entityId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "GetAssetReadUrlResponse": {
+        "type": "object",
+        "required": [
+          "read"
+        ],
+        "properties": {
+          "read": {
+            "$ref": "#/components/schemas/AssetReadUrl"
+          }
+        }
+      },
+      "AssetReadUrl": {
+        "type": "object",
+        "required": [
+          "provider",
+          "bucket",
+          "endpoint",
+          "host",
+          "objectKey",
+          "expiresAt",
+          "signedUrl"
+        ],
+        "properties": {
+          "provider": {
+            "type": "string"
+          },
+          "bucket": {
+            "type": "string"
+          },
+          "endpoint": {
+            "type": "string"
+          },
+          "host": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "signedUrl": {
+            "type": "string"
+          }
+        }
+      },
+      "ExternalEditorProjectRenameRequest": {
+        "type": "object",
+        "required": [
+          "title"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorCanvasSaveRequest": {
+        "type": "object",
+        "required": [
+          "viewport",
+          "layers"
+        ],
+        "properties": {
+          "viewport": {
+            "$ref": "#/components/schemas/EditorCanvasViewport"
+          },
+          "layers": {
+            "type": "object",
+            "description": "画布图层 JSON，最大约 256KB。"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorAssetFolderCreateRequest": {
+        "type": "object",
+        "required": [
+          "label"
+        ],
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "sortOrder": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 100
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorAssetFolderUpdateRequest": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "collapsed": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorAssetCreateRequest": {
+        "type": "object",
+        "required": [
+          "folderId",
+          "label",
+          "imageSrc",
+          "width",
+          "height",
+          "sourceType"
+        ],
+        "properties": {
+          "folderId": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "imageSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string"
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "provider": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "taskId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorProjectResourceCreateRequest": {
+        "type": "object",
+        "required": [
+          "imageSrc",
+          "width",
+          "height",
+          "sourceType"
+        ],
+        "properties": {
+          "imageSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string"
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "provider": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "taskId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sourceResourceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorAssetUpdateRequest": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "folderId": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "ExternalEditorProjectResponse": {
+        "type": "object",
+        "required": [
+          "project"
+        ],
+        "properties": {
+          "project": {
+            "$ref": "#/components/schemas/EditorProject"
+          }
+        }
+      },
+      "ExternalEditorProjectRecentResponse": {
+        "type": "object",
+        "required": [
+          "project"
+        ],
+        "properties": {
+          "project": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProject"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      },
+      "ExternalEditorProjectListResponse": {
+        "type": "object",
+        "required": [
+          "projects"
+        ],
+        "properties": {
+          "projects": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorProject"
+            }
+          }
+        }
+      },
+      "ExternalEditorProjectDeleteResponse": {
+        "type": "object",
+        "required": [
+          "deletedProjectId"
+        ],
+        "properties": {
+          "deletedProjectId": {
+            "type": "string"
+          }
+        }
+      },
+      "ExternalEditorAssetLibraryResponse": {
+        "type": "object",
+        "required": [
+          "library"
+        ],
+        "properties": {
+          "library": {
+            "$ref": "#/components/schemas/EditorAssetLibrary"
+          }
+        }
+      },
+      "ExternalEditorAssetFolderResponse": {
+        "type": "object",
+        "required": [
+          "folder"
+        ],
+        "properties": {
+          "folder": {
+            "$ref": "#/components/schemas/EditorAssetFolder"
+          }
+        }
+      },
+      "ExternalEditorAssetFolderDeleteResponse": {
+        "type": "object",
+        "required": [
+          "library"
+        ],
+        "properties": {
+          "library": {
+            "$ref": "#/components/schemas/EditorAssetLibrary"
+          }
+        }
+      },
+      "ExternalEditorAssetResponse": {
+        "type": "object",
+        "required": [
+          "asset"
+        ],
+        "properties": {
+          "asset": {
+            "$ref": "#/components/schemas/EditorAsset"
+          }
+        }
+      },
+      "ExternalEditorProjectResourceResponse": {
+        "type": "object",
+        "required": [
+          "resource"
+        ],
+        "properties": {
+          "resource": {
+            "$ref": "#/components/schemas/EditorProjectResource"
+          }
+        }
+      },
+      "EditorProject": {
+        "type": "object",
+        "required": [
+          "projectId",
+          "title",
+          "canvas",
+          "viewport",
+          "layers",
+          "resources",
+          "updatedAt"
+        ],
+        "properties": {
+          "projectId": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "canvas": {
+            "$ref": "#/components/schemas/EditorCanvas"
+          },
+          "viewport": {
+            "$ref": "#/components/schemas/EditorCanvasViewport"
+          },
+          "layers": {
+            "type": "object"
+          },
+          "resources": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorProjectResource"
+            }
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "EditorCanvas": {
+        "type": "object",
+        "required": [
+          "canvasId",
+          "projectId",
+          "title",
+          "viewport",
+          "layers",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "canvasId": {
+            "type": "string"
+          },
+          "projectId": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "viewport": {
+            "$ref": "#/components/schemas/EditorCanvasViewport"
+          },
+          "layers": {
+            "type": "object"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "EditorCanvasViewport": {
+        "type": "object",
+        "required": [
+          "x",
+          "y",
+          "scale"
+        ],
+        "properties": {
+          "x": {
+            "type": "number"
+          },
+          "y": {
+            "type": "number"
+          },
+          "scale": {
+            "type": "number",
+            "minimum": 0.01,
+            "maximum": 8
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorProjectResource": {
+        "type": "object",
+        "required": [
+          "resourceId",
+          "projectId",
+          "imageSrc",
+          "width",
+          "height",
+          "sourceType",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "resourceId": {
+            "type": "string"
+          },
+          "projectId": {
+            "type": "string"
+          },
+          "imageSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string"
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "provider": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "taskId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sourceResourceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "EditorAssetLibrary": {
+        "type": "object",
+        "required": [
+          "folders",
+          "assets"
+        ],
+        "properties": {
+          "folders": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorAssetFolder"
+            }
+          },
+          "assets": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorAsset"
+            }
+          }
+        }
+      },
+      "EditorAssetFolder": {
+        "type": "object",
+        "required": [
+          "folderId",
+          "label",
+          "sortOrder",
+          "collapsed",
+          "systemDefault",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "folderId": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "sortOrder": {
+            "type": "integer"
+          },
+          "collapsed": {
+            "type": "boolean"
+          },
+          "systemDefault": {
+            "type": "boolean"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "EditorAsset": {
+        "type": "object",
+        "required": [
+          "assetId",
+          "folderId",
+          "label",
+          "imageSrc",
+          "width",
+          "height",
+          "sourceType",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "assetId": {
+            "type": "string"
+          },
+          "folderId": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "imageSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string"
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "provider": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "taskId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "JsonValue": {
+        "description": "任意 JSON 值。"
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      },
+      "EditorImageGenerationRequest": {
+        "type": "object",
+        "required": [
+          "prompt"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "size": {
+            "type": "string",
+            "description": "兼容旧 size 入参；未传 aspectRatio/imageSize 时生效。",
+            "enum": [
+              "1024x1024",
+              "1536x1024",
+              "1024x1536",
+              "2048x1152",
+              "2048x2048",
+              "2k-16:9",
+              "1:1",
+              "16:9",
+              "9:16"
+            ]
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "spec",
+              "character",
+              "quick-edit",
+              "ui-design",
+              "publication-material"
+            ],
+            "default": "spec"
+          },
+          "model": {
+            "type": "string",
+            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时沿用编辑器默认。"
+          },
+          "aspectRatio": {
+            "type": "string",
+            "enum": [
+              "1:1",
+              "2:3",
+              "3:2",
+              "9:16",
+              "16:9"
+            ],
+            "default": "1:1"
+          },
+          "imageSize": {
+            "type": "string",
+            "enum": [
+              "0.5K",
+              "1K",
+              "2K"
+            ],
+            "default": "1K"
+          },
+          "referenceImageSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "图片 Data URL。quick-edit 最多 9 张，其它模式最多使用前 5 张。"
+            },
+            "maxItems": 9
+          },
+          "projectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "传 project 时写入默认项目素材文件夹；传具体 folderId 时写入该文件夹。"
+          },
+          "assetLabel": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "写入素材库时使用的素材名称。"
+          },
+          "sourceResourceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "canvasCompletion": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorCanvasGenerationCompletion"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "带项目上下文生成时，服务端据此直接写入画布完成态并返回最新项目快照。"
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorCanvasGenerationCompletion": {
+        "type": "object",
+        "required": [
+          "dialogId",
+          "title",
+          "placeholder"
+        ],
+        "properties": {
+          "dialogId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "title": {
+            "type": "string"
+          },
+          "placeholder": {
+            "$ref": "#/components/schemas/EditorCanvasGenerationPlaceholder"
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorCanvasGenerationPlaceholder": {
+        "type": "object",
+        "required": [
+          "x",
+          "y",
+          "width",
+          "height",
+          "originalWidth",
+          "originalHeight"
+        ],
+        "properties": {
+          "x": {
+            "type": "number"
+          },
+          "y": {
+            "type": "number"
+          },
+          "width": {
+            "type": "number",
+            "minimum": 1
+          },
+          "height": {
+            "type": "number",
+            "minimum": 1
+          },
+          "originalWidth": {
+            "type": "number",
+            "minimum": 1
+          },
+          "originalHeight": {
+            "type": "number",
+            "minimum": 1
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorImageEditRequest": {
+        "type": "object",
+        "required": [
+          "prompt",
+          "sourceImageSrc"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sourceImageSrc": {
+            "type": "string",
+            "description": "待重绘/调整的图片 Data URL。"
+          },
+          "projectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetKind": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetLabel": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sourceResourceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorImageGenerationResponse": {
+        "type": "object",
+        "required": [
+          "imageSrc",
+          "width",
+          "height",
+          "sourceType",
+          "prompt",
+          "model",
+          "provider",
+          "taskId"
+        ],
+        "properties": {
+          "imageSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string",
+            "const": "generated"
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "taskId": {
+            "type": "string"
+          },
+          "resource": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProjectResource"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "asset": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorAsset"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "project": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProject"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          }
+        }
+      },
+      "EditorIconSpritesheetGenerationRequest": {
+        "type": "object",
+        "required": [
+          "referenceImageSrc",
+          "iconDescriptions",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "referenceImageSrc": {
+            "type": "string",
+            "description": "规范图/参考图 Data URL。"
+          },
+          "iconDescriptions": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 100,
+            "items": {
+              "type": "string"
+            }
+          },
+          "model": {
+            "type": "string",
+            "default": "gemini-3.1-flash-image-preview"
+          },
+          "aspectRatio": {
+            "type": "string",
+            "enum": [
+              "1:1",
+              "2:3",
+              "3:2",
+              "9:16",
+              "16:9"
+            ],
+            "default": "1:1"
+          },
+          "imageSize": {
+            "type": "string",
+            "enum": [
+              "0.5K",
+              "1K",
+              "2K"
+            ],
+            "default": "1K"
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "projectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorUiDesignAssetExtractionRequest": {
+        "type": "object",
+        "required": [
+          "sourceImageSrc"
+        ],
+        "properties": {
+          "sourceImageSrc": {
+            "type": "string",
+            "description": "UI 设计图 Data URL。"
+          },
+          "projectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "generationInputs": {
+            "$ref": "#/components/schemas/JsonValue"
+          },
+          "assetFolderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "spritesheetLabel": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorIconSpritesheetIconResult": {
+        "type": "object",
+        "required": [
+          "name",
+          "imageSrc",
+          "width",
+          "height"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "imageSrc": {
+            "type": "string"
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "resource": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProjectResource"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "asset": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorAsset"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      },
+      "EditorIconSpritesheetGenerationResponse": {
+        "type": "object",
+        "required": [
+          "spritesheetImageSrc",
+          "spritesheetWidth",
+          "spritesheetHeight",
+          "iconImageSrcs",
+          "prompt",
+          "model",
+          "provider",
+          "taskId",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "spritesheetImageSrc": {
+            "type": "string"
+          },
+          "spritesheetWidth": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "spritesheetHeight": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "iconImageSrcs": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
+            }
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "taskId": {
+            "type": "string"
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "spritesheetResource": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorProjectResource"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "spritesheetAsset": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorAsset"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      },
+      "EditorCharacterAnimationGenerationRequest": {
+        "type": "object",
+        "required": [
+          "sourceLayerId",
+          "sourceImageSrc",
+          "sourceWidth",
+          "sourceHeight",
+          "promptText",
+          "resolution",
+          "ratio",
+          "frameCount",
+          "durationSeconds",
+          "priceMudPoints",
+          "model"
+        ],
+        "properties": {
+          "sourceLayerId": {
+            "type": "string"
+          },
+          "sourceImageSrc": {
+            "type": "string"
+          },
+          "sourceWidth": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceHeight": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "promptText": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4000
+          },
+          "resolution": {
+            "type": "string",
+            "enum": [
+              "480p",
+              "720p"
+            ],
+            "default": "480p"
+          },
+          "ratio": {
+            "type": "string",
+            "enum": [
+              "same",
+              "1:1",
+              "4:3",
+              "16:9",
+              "9:16",
+              "3:4"
+            ],
+            "default": "same"
+          },
+          "frameCount": {
+            "type": "integer",
+            "enum": [
+              32,
+              40,
+              48
+            ]
+          },
+          "durationSeconds": {
+            "type": "integer",
+            "enum": [
+              4,
+              5,
+              6
+            ]
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "model": {
+            "type": "string",
+            "const": "seedance2.0-fast"
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorCharacterAnimationFrame": {
+        "type": "object",
+        "required": [
+          "frameIndex",
+          "imageSrc",
+          "width",
+          "height"
+        ],
+        "properties": {
+          "frameIndex": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "imageSrc": {
+            "type": "string"
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      },
+      "EditorCharacterAnimationGenerationResponse": {
+        "type": "object",
+        "required": [
+          "ok",
+          "taskId",
+          "model",
+          "prompt",
+          "previewVideoPath",
+          "frames",
+          "frameCount",
+          "durationSeconds",
+          "frameWidth",
+          "frameHeight",
+          "fps",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "taskId": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "previewVideoPath": {
+            "type": "string"
+          },
+          "frames": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EditorCharacterAnimationFrame"
+            }
+          },
+          "frameCount": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "durationSeconds": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "frameWidth": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "frameHeight": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "fps": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "EditorVideoGenerationRequest": {
+        "type": "object",
+        "required": [
+          "prompt",
+          "model",
+          "aspectRatio",
+          "durationSeconds",
+          "resolution",
+          "mode",
+          "sound",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4000
+          },
+          "model": {
+            "type": "string",
+            "enum": [
+              "seedance2.0",
+              "seedance2.0-fast",
+              "kling3.0",
+              "kling3.0-omni",
+              "veo3.1",
+              "veo3.1-fast"
+            ]
+          },
+          "aspectRatio": {
+            "type": "string",
+            "const": "16:9"
+          },
+          "durationSeconds": {
+            "type": "integer",
+            "enum": [
+              4,
+              5
+            ]
+          },
+          "resolution": {
+            "type": "string",
+            "enum": [
+              "480p",
+              "720p"
+            ]
+          },
+          "mode": {
+            "type": "string",
+            "const": "std"
+          },
+          "sound": {
+            "type": "string",
+            "const": "off"
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "referenceImageSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "公网 URL、asset://、OSS object key 或图片 Data URL。仅 Seedance 2.0 系列支持。"
+            },
+            "maxItems": 9
+          },
+          "referenceVideoSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "公网 URL、asset:// 或 OSS object key。仅 Seedance 2.0 系列支持。"
+            },
+            "maxItems": 3
+          },
+          "referenceAudioSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "公网 URL、asset://、OSS object key 或音频 Data URL。仅 Seedance 2.0 系列支持。"
+            },
+            "maxItems": 3
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorVideoGenerationResponse": {
+        "type": "object",
+        "required": [
+          "ok",
+          "videoSrc",
+          "width",
+          "height",
+          "sourceType",
+          "prompt",
+          "model",
+          "provider",
+          "taskId",
+          "durationSeconds",
+          "resolution",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "videoSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string",
+            "const": "generated"
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "taskId": {
+            "type": "string"
+          },
+          "durationSeconds": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "resolution": {
+            "type": "string"
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "EditorSoundEffectGenerationRequest": {
+        "type": "object",
+        "required": [
+          "prompt",
+          "duration",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "model": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "default": "audio1.0"
+          },
+          "duration": {
+            "type": "integer",
+            "minimum": 2,
+            "maximum": 10
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorBackgroundMusicGenerationRequest": {
+        "type": "object",
+        "required": [
+          "gptDescriptionPrompt",
+          "makeInstrumental",
+          "priceMudPoints"
+        ],
+        "properties": {
+          "gptDescriptionPrompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "makeInstrumental": {
+            "type": "boolean",
+            "const": true
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "additionalProperties": false
+      },
+      "EditorAudioGenerationResponse": {
+        "type": "object",
+        "required": [
+          "ok",
+          "audioSrc",
+          "width",
+          "height",
+          "sourceType",
+          "prompt",
+          "model",
+          "provider",
+          "taskId",
+          "priceMudPoints",
+          "audioKind"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "audioSrc": {
+            "type": "string"
+          },
+          "objectKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "assetObjectId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "width": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "height": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "sourceType": {
+            "type": "string",
+            "const": "generated"
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "actualPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "taskId": {
+            "type": "string"
+          },
+          "priceMudPoints": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "audioKind": {
+            "type": "string",
+            "enum": [
+              "sound-effect",
+              "background-music"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md b/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
index 218b02f06..cec5df42a 100644
--- a/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
+++ b/docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md
@@ -151,15 +151,15 @@ WF-*
 1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
 2. multipart 参考图固定包含默认木鱼图 `/wooden-fish/default-hit-object.png`，作为基础结构和画风参考；
 3. 若用户上传参考图，该图只作为新主题参考追加到同一次 image2 edits 请求，不直接进入运行态；
-4. 尺寸固定 `1:1`，必须输出绿色背景主体图（纯绿色绿幕），背景为单一纯绿色 `#00FF00`，并显式禁止黑底、白底、棋盘格、纸板底或任何其它实底背景；
+4. 尺寸固定 `1:1`，必须输出单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，并显式禁止黑底、白底、棋盘格、纸板底或任何其它实底背景；
 5. 提示词严格使用：
 
 ```text
-生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。
+生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，背景必须严格使用 #00FF00 / RGB(0,255,0) 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。
 新主题为：（用户提供参考图或用户输入关键词）
 ```
 
-敲击物图案落盘前，`api-server` 必须只对第一步生成的纯绿色绿幕背景执行去绿处理，把绿色背景转成真实透明 alpha PNG；不得对黑底、白底或其它未知实底执行泛抠图，避免误伤玉米等主体像素。去绿处理必须保留主体内部深色结构和主题细节。
+敲击物图案落盘前，`api-server` 必须只对第一步生成的单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景执行去绿处理，把绿色背景转成真实透明 alpha PNG；不得对黑底、白底或其它未知实底执行泛抠图，避免误伤玉米等主体像素。去绿处理必须保留主体内部深色结构和主题细节。
 
 背景环境图生成流程固定为：
 
@@ -178,12 +178,12 @@ WF-*
 
 1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
 2. multipart 参考图固定包含第一步去除绿色背景后的敲击物主体图，以及第二步生成的背景环境图；
-3. 尺寸固定 `1:1`，必须输出绿色背景主体图（纯绿色绿幕），后端落库前执行同一套去绿背景处理；
+3. 尺寸固定 `1:1`，必须输出单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，后端落库前执行同一套去绿背景处理；
 4. 按主题、画风、材质和配色生成左上角返回按钮图，但参考图只用于约束圆形底色和中央左箭头的颜色搭配，不得借鉴复杂造型、花纹、浮雕边、异形外框或装饰图案；按钮必须始终是标准圆形，主体视觉尺寸比当前模板再放大约 50%，圆形外沿必须有与主题色搭配的干净外描边，中央只保留单个清晰左箭头或返回箭头，不得包含文字、数字、水印、额外 UI 面板、木槌或敲击道具；
 5. 提示词严格使用：
 
 ```text
-生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，按钮主体在画布中的视觉尺寸比当前模板再放大约 50%，圆心居中，圆形外沿加一圈和主题色搭配的干净外描边，让它更像一个按钮，但仍然只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 UI 面板、木槌或敲击道具。尺寸1:1，输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影。按钮主体边缘干净，后续由服务端扣除绿色背景；按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请仅在圆形底色上使用偏深、偏黄或偏蓝的主题绿色，并用更高对比的箭头颜色区分。
+生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，按钮主体在画布中的视觉尺寸比当前模板再放大约 50%，圆心居中，圆形外沿加一圈和主题色搭配的干净外描边，让它更像一个按钮，但仍然只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 UI 面板、木槌或敲击道具。尺寸1:1，输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，背景必须严格使用 #00FF00 / RGB(0,255,0) 且平整无纹理、无渐变、无阴影。按钮主体边缘干净，后续由服务端扣除绿色背景；按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请仅在圆形底色上使用偏深、偏黄或偏蓝的主题绿色，并用更高对比的箭头颜色区分。
 主题为：（用户提供参考图或用户输入关键词）
 ```
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 50d2a6fde..fa3a5a343 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,6 +16,94 @@
 
 ---
 
+## 2026-06-21 图片画布生成完成态由后端写入画布布局
+
+- 背景：图片画布角色形象等长耗时生成在服务端完成后，如果浏览器已刷新或原 HTTP 回调丢失，前端无法再把生成结果图层和 `generation-dialog` 完成态写回 `editor_canvas.layers_json`，用户会继续看到“生成中”卡片。
+- 决策：图片生成请求在有项目上下文时携带 `canvasCompletion`（生成器 `dialogId`、结果标题和占位框）；`api-server` 在生成成功并创建 `editor_project_resource` / `editor_asset` 后，直接读取当前项目布局，只有当前布局仍存在对应生成器时才插入轻量结果图层，把生成器标记为 `idle` 并写入 `generatedLayerId`，沿用后端当前 viewport 保存 layout 后返回最新项目快照。前端只应用后端快照刷新显示，不再把生成完成态作为正式业务真相，也不在项目加载时根据资源行推断完成态。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、图片画布生成提交工作流、项目快照 hydrate / persistence、图片画布技术方案和排障记录。
+- 验证方式：`cargo test -p api-server editor_canvas_generation_completion --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-21 图片画布参考图元数据只保存项目内行引用
+
+- 背景：参考图如果把 Data URL、signed URL 或 `objectKey` 写入 `generationInputs` 或生成器布局快照，会撑大资源 / 素材 / 画布 JSON，也无法稳定索引到项目内用户可见行数据。
+- 决策：`generationInputs.references` 只保存 `{ title, label, refType, refId }`，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`。生成器 `itemType="generation-dialog"` 布局快照中的参考图也只保存 `resourceId/sourceAssetId` 和展示 label，不保存图片 Data URL、signed URL 或 `objectKey`；提交生成请求前的内存态可以临时持有 `src/objectKey`，刷新恢复时从 `editor_project_resource` / `editor_asset` 行补回请求所需图片源。不兼容旧 `src` 型参考图元数据。
+- 影响范围：图片画布生成输入快照、生成器布局保存 / 恢复、参考图上传工作流、元数据弹窗和图片画布技术文档。
+- 验证方式：运行图片画布生成模型、生成提交、上传工作流、项目持久化、元数据弹窗相关前端测试，执行 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-19 外部 OpenAPI 与 API Key 管理走 server-rs 正式链路
+
+- 背景：外部调用方需要稳定调用图片画布项目创建、画布布局保存和编辑器美术生图能力，同时需要可撤销的开发者凭据，不能依赖前端临时状态或人工分发密钥。
+- 决策：外部 API 固定放在 `/api/external/v1` 命名空间，v1 暴露素材直传凭证 / asset object 确认 / 签名读取、项目列表 / 最近 / 创建 / 读取 / 重命名 / 删除、默认画布保存、账号级素材库、项目资源记录、编辑器图片 / 视频 / 音频生成和 `/api/external/v1/openapi.json`。API Key 管理走登录态 `/api/profile/api-keys`，外部调用使用 `Authorization: Bearer tnr_sk_xxx`；后端只保存 `key_hash` 和 `key_prefix`，明文只在创建响应返回一次。外部 API 鉴权、项目 / 画布 / 素材写回全部经 `api-server -> spacetime-client -> spacetime-module`，生成素材成功后按请求写入账号级 `editor_asset`，带 `projectId` 时写入 `editor_project_resource`；外部确认 asset object 时 owner 固定为 API Key 所属账号。API Key 管理接口不进入外部 OpenAPI JSON。
+- 影响范围：`server-rs/crates/api-server/src/external_*`、`server-rs/crates/api-server/src/modules/external_api.rs`、`server-rs/crates/spacetime-module/src/external_api_key_storage.rs`、`server-rs/crates/spacetime-client/src/external_api_key.rs`、`docs/openapi/genarrative-external-v1.openapi.json` 和后端数据契约文档。
+- 验证方式：`cargo test -p api-server external_api --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server external_editor_api --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+
+## 2026-06-19 图片画布素材生成元数据上移到资源和素材
+
+- 背景：角色、图标、UI 设计图、视频和音频等生成结果会在图片信息页展示用户可见输入快照；此前这些 `assetKind/generationInputs` 主要保存在画布 layer JSON 中，素材进入账号级素材库后跨项目复用和刷新恢复都依赖画布布局，不符合素材库作为账号级事实源的边界。
+- 决策：普通图层的新保存不再把 `assetKind/generationInputs` 写入 `editor_canvas.layers_json`。`editor_project_resource` 保存项目画布资源快照的 `asset_kind/generation_inputs_json`，`editor_asset` 保存账号级素材的同名元数据；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `projectId` / `assetFolderId` 时由后端创建新 resource / asset 并把快照回传前端，前端只用回包更新画布图层和素材栏，不再把同一生成结果二次调用保存接口。前端加载时优先从 resource / asset 恢复素材类别和生成输入快照，旧 layout 中的同名字段只作为历史兼容兜底。生成器对象本身仍作为 `itemType="generation-dialog"` 保存在画布布局中。
+- 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/mapper/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、图片画布 hydrate / serialize / project persistence / asset library 代码和后端数据契约文档。
+- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`，并按需补充 `cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-19 图片画布生成按钮价格统一绑定模型定价配置
+
+- 背景：图片画布的生成图片、生成视频、生成规范、生成角色、生成素材、生成 UI、宣发素材、快速编辑、重绘和音频生成入口都在按钮内显示泥点；如果按钮文案、前端提交和后端校验各自写固定数值，后续调整模型价格会出现展示价、提交价和扣费价不一致。
+- 决策：所有画板生成按钮价格必须从 `src/components/image-editor/ImageCanvasGenerationModel.ts` 的模型定价配置函数计算；需要提交 `priceMudPoints` 的视频、角色动画、图标素材、音效和背景音乐也使用同一函数。后端用 `server-rs/crates/api-server/src/editor_generation_config.rs` 的同名语义配置重新计算并校验 / 扣费。当前正式模型均已覆盖定价：图片类 `nanobanana2`（真实模型 `gemini-3.1-flash-image-preview`）为 12，`gpt-image-2` 为 20；生成规范固定 `gpt-image-2` 为 5；视频按模型和清晰度分档，`seedance2.0-fast` 为 480p 每秒 10 / 720p 每秒 20，`seedance2.0` 为 12 / 24，`kling3.0` 为 15 / 30，`kling3.0-omni` 为 20 / 40，Veo 旧布局兼容价仍为 10 / 20。画板 UI 统一显示 `nanobanana2`，历史输入或旧布局中的 `nano-banana` 必须归一到真实模型 ID 后再提交和计费。
+- 影响范围：图片画布生成类面板、生成提交模型、编辑器图片 / 视频 / 音频 BFF、`editor_generation_config` 和 Lovart 生成类面板文档。
+- 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationModel.test.ts src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 2026-06-18 图片画布 UI 设计图提取素材保留图集
+
+- 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
+- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，固定调用 `/api/editor/ui-designs/assets/extractions`，后端固定 `gpt-image-2` 和提示词 `提取画面中的所有独立并整理成spritesheet`，返回结构复用图标 spritesheet 响应。图标生成与 UI 提取都必须把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。
+- 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
+- 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
+- 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
+
+## 2026-06-18 `/creation` 独立为陶泥儿创作工具主页
+
+- 背景：图片画布项目已经成为独立项目资产，旧“创作”站内 Tab 和一级“草稿”入口不能清晰表达桌面端创作工具主页与项目管理入口。
+- 决策：桌面端新增独立 `/creation` 创作工具主页，桌面端直接打开站点首页 `/` 时也默认展示新版创作主页；顶级“创作”入口跳转 `/creation`，原“草稿”入口替换为“项目”并跳转 `/project`。移动端首页 `/` 继续保持原推荐首页，移动端隐藏“创作”和“项目”入口，但不拦截直接 URL。页面文案统一使用“陶泥儿”，外部品牌只作为设计参考，不进入用户可见 UI、测试名、产品文案或验收口径。`陶泥儿精选` 是用户素材瀑布流，不展示玩法入口列表；创作入口事实源继续来自 `/api/creation-entry/config`，项目入口通过 `createEditorProject` 和 `/editor/canvas?projectid=xxx` 链路进入画布。
+- 影响范围：平台入口导航、`SelectionStage` 路由、`/creation` 首页、`/project` 项目入口、`/editor/canvas` 项目打开链路、“我的”页快捷入口和创作入口相关测试。
+- 验证方式：桌面 `/` 初始阶段和 `/creation` 解析为创作主页，移动端 `/` 仍是推荐首页，`/creation/<play>` 仍进入对应玩法工作台；桌面导航显示“创作 / 项目”且不显示“草稿”；移动端底部不显示“创作 / 项目”；页面不出现外站品牌或 `Discord` 字样；新建项目进入 `/editor/canvas?projectid=xxx`。
+- 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-18 图片画布 Seedance 2.0 参考媒体提交边界
+
+- 背景：`/editor/canvas` 生成视频需要严格对齐火山 Seedance 2.0 多模态参考输入；参考视频若继续走 Base64 / `data:video` 会超过请求体并被上游拒绝，参考音频单独输入和非 Seedance 模型携带参考字段也会违反文档契约。
+- 决策：仅 `seedance2.0-fast` / `seedance2.0` 可提交参考图片、参考视频、参考音频；图片 0~9、视频 0~3、音频 0~3，音频必须搭配图片或视频。参考视频只能提交公网 URL、`asset://` 或画板资源 `objectKey`，禁止 `data:video/*`；视频 / 音频上传先走 OSS 直传和 asset_object confirm，前端保存 signed URL 预览但提交优先 `objectKey`，后端统一重新签名给 Ark。Ark body 按 `image_url` / `video_url` / `audio_url` + `reference_*` role 构造，并显式发送 `generate_audio:false`。
+- 影响范围：图片画布生成视频面板、参考媒体上传工作流、`editorReferenceUploadClient`、`ImageCanvasGenerationSubmissionModel`、`shared-contracts`、`api-server` 编辑器视频 BFF、Lovart 生成类面板文档。
+- 验证方式：运行 `npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、火山 Seedance 2.0 任务创建文档。
+
+## 2026-06-21 图片画布生成视频参数扩展
+
+- 背景：编辑器画布生成视频需要开放更多 Lovart 式参数，同时保留模型能力边界；`seedance2.0-fast` 不支持 `1080p`，联网搜索暂没有可确认的 Ark 视频生成 body 字段。
+- 决策：生成视频参数面板支持比例 `16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9`，时长为 4 到 15 秒整数 slider，清晰度支持 `480p / 720p / 1080p`；`seedance2.0-fast` 不展示可用 `1080p`，从其它模型的 `1080p` 切回 Fast 时自动降到 `720p`，后端也拒绝 `seedance2.0-fast + 1080p`。静音只作为一个 toggle 展示，默认有声并映射 `sound=on` / Ark `generate_audio=true`；关闭静音时传 `sound=off` / `generate_audio=false`。`webSearchEnabled` 默认随请求提交为 `true`，但前端不展示联网搜索开关，后端当前只接收契约字段，不向 Ark 透传未知参数。
+- 影响范围：图片画布生成视频面板、生成提交模型、画布项目快照恢复、`editorProjectClient`、`shared-contracts`、`api-server` 编辑器视频 BFF、编辑器技术文档。
+- 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts`、`cargo test -p shared-contracts editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 2026-06-18 图片画布生成音乐入口作为音频图层接入
+
+- 背景：图片画布底部生成工具需要补齐游戏音效和游戏背景音乐生成，既要复用现有 Lovart 式画布生成器快照、占位避让和持久化，又不能把音频能力并入图片素材库或视觉小说专用音频开关。
+- 决策：`/editor/canvas` 新增底部 `生成音乐` 入口，点击后先弹出“生成游戏音效 / 生成游戏背景音乐”选项框，再分别创建 `audio-sound-effect` 或 `audio-background-music` 生成器；生成结果作为 `mediaType="audio"` 的画布音频卡保存，`assetKind` 分别为 `sound-effect` / `background-music`。音效请求字段固定映射 Vidu `prompt/model/duration`，模型固定 `audio1.0`、时长严格 `2-10` 秒；背景音乐请求字段固定映射 `gpt_description_prompt` 且 `make_instrumental=true`。
+- 影响范围：图片画布生成工作流、前端 editorProjectClient、`shared-contracts`、`platform-audio`、`api-server` 编辑器音频 BFF、图片画布技术方案和音乐生成入口设计文档。
+- 验证方式：运行编辑器生成入口 / 提交 / 音频图层相关前端测试，`platform-audio` 请求体测试，`shared-contracts` editor audio 序列化测试，`api-server` editor audio 归一化测试，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 2026-06-17 图片画布生成占位统一避让落点
+
+- 背景：图片画布的普通图片、规范、角色、图标、视频和 UI 设计图生成入口都会先在画布中新建“即将生成”的占位图；若各入口直接使用当前视口中心，容易压住已有图片或已有生成占位，Lovart 式连续创作体验不稳定。
+- 决策：所有会新建画布生成占位的入口统一经过 `ImageCanvasGenerationPlacementModel` 计算落点。模型以当前视口世界中心为目标，避让所有未隐藏画布图层和 active / inactive generation dialog placeholder，按 32px 画布世界坐标间距外扩阻挡矩形，选择距离当前屏幕中心对应画板位置最近且不重叠的位置。选定后立即调用 `centerViewportOnPlacement(...)`，保持当前缩放比例不变，只平移画布 viewport，让屏幕中心移动到新占位中心。
+- 影响范围：`/editor/canvas` 图片画布生成入口、`useImageCanvasGenerationWorkflow`、`ImageCanvasGenerationPlacementModel`、图片画布技术方案和 Lovart 生成类面板文档。
+- 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
 ## 2026-06-13 Pingora 低端口直连只通过显式 systemd drop-in 启用
 
 - 背景：`genarrative-pingora-gateway.service` 默认以 `genarrative` 非 root 用户运行，shadow 阶段只监听本机高端口；如果正式评估让 Pingora 直接绑定公网 `80/443`，需要低端口绑定能力，但不能让 Server-Provision 或默认 service 自动改变接流边界。
@@ -104,17 +192,9 @@
 - 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。
 - 决策：`.codex/skills/` 下只保留 `spacetimedb-cli`、`spacetimedb-concepts`、`spacetimedb-rust` 三个本地 SpacetimeDB skill；删除 `spacetimedb-typescript`、`spacetimedb-csharp`、`spacetimedb-unity`。前端 / Node 侧如需处理 SpacetimeDB 订阅或绑定，按当前生成绑定、项目代码和官方文档核对，不再依赖仓库内单独 TypeScript skill。
 - 影响范围：`AGENTS.md` 的 SpacetimeDB skill 清单、`.codex/skills/` 本地 skill 维护范围、后续 SpacetimeDB 设计 / CLI / Rust module 开发协作口径。
-- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md docs/project-memory/shared-memory/decision-log.md` 和 `npm run check:encoding`。
+- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md .hermes/shared-memory/decision-log.md` 和 `npm run check:encoding`。
 - 关联文档：`AGENTS.md`、`.codex/skills/spacetimedb-cli/SKILL.md`、`.codex/skills/spacetimedb-concepts/SKILL.md`、`.codex/skills/spacetimedb-rust/SKILL.md`。
 
-## 2026-06-18 长期项目记忆固定读取 `docs/project-memory/`
-
-- 背景：项目记忆已从仓库 `.hermes/` 迁移到 `docs/project-memory/`，但部分协作说明仍把 `.hermes/` 写成共享记忆或计划容器，容易让 Agent 和开发者回到旧路径。
-- 决策：长期项目记忆、计划和 TODO 只从 `docs/project-memory/` 读取和维护；`.hermes/` 仅保存 Hermes 专用的仓库级 skills、plugins 和启用说明。`AGENTS.md` 的复杂任务阅读清单不再把 `.hermes/README.md` 放在项目记忆入口中，只有使用 Hermes 工具资源时才读取它。
-- 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/README.md`、`docs/project-memory/shared-memory/`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
-- 验证方式：扫描 `AGENTS.md`、当前 `docs/` 与 `.hermes/README.md`，确认当前口径不再把 `.hermes/` 描述为长期项目记忆路径。
-- 关联文档：`AGENTS.md`、`docs/project-memory/README.md`、`.hermes/README.md`。
-
 ## 2026-06-13 图片大图预览统一为黑底全屏查看器
 
 - 背景：`CreativeImageInputPanel` 的参考图 / 主图预览曾使用白底 `UnifiedModal` 工具弹窗，移动端会透出原页面背景，且不能全屏查看、缩放或拖拽细节。
@@ -131,6 +211,14 @@
 - 验证方式：生成页不出现“生成队列”区域；登录用户进入“我的”页且队列有 pending/running 或当前 job 为 queued/running/failed 时显示队列卡；退出登录或切换账号时不保留旧账号队列概览。前端验证运行 `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
 
+## 2026-06-13 `/editor/agent` AI Web 工程编辑器采用静态沙箱预览 MVP
+
+- 背景：`/editor/agent` 需要承载浏览器内类似 IDE 的 AI Web 工程编辑和实时预览能力，但 AI 生成工程的构建和运行不能进入 Genarrative 主站 JS 上下文、当前仓库源码目录或 api-server 进程。
+- 决策：第一版采用“平台编辑器壳 `/editor/agent` + api-server 控制面 + 独立 `web-project-runner` worker + 独立 preview origin”的四层结构。MVP 只支持固定 React / Vite / TypeScript 静态模板、虚拟文件系统、结构化 AI patch、平台固定构建命令、独立 runner 静态构建和独立域 iframe 预览；明确不做 HMR、终端 shell、后端服务、任意端口代理、任意 npm 安装、AI 自定义 shell script 或主站同源预览。
+- 影响范围：`/editor/agent` 前端入口、api-server Web project 控制面、Web project runtime job、runner 部署、preview gateway、artifact store、安全验收和后续作品化发布链路。
+- 验证方式：Phase 0 必须先完成技术方案、威胁模型和验收清单；Phase 1 只能在路径校验、runner 资源限制、网络隔离、preview token、iframe/CSP、失败保留上一版预览和刷新恢复验收口径明确后进入编码。
+- 关联文档：`docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md`、`docs/technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md`、`docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md`。
+
 ## 2026-06-12 外部生成 worker 扩展到跳一跳、拼消消和敲木鱼
 
 - 背景：外部图片生成已从 HTTP 长请求迁到 `external_generation_job` 队列；跳一跳、拼消消和敲木鱼继续扩展时需要统一 job 粒度、前端等待展示和本地 / 生产验证口径。
@@ -1122,7 +1210,7 @@
 ## 2026-05-22 敲木鱼图片创作采用三图 image2 链路
 
 - 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景和主题化返回按钮；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
-- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为三步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 绿色背景主体图；`api-server` 先对这张绿幕图执行去绿背景处理并写回 `hitObjectAsset`。第二步必须以第一步抠图完成后的透明敲击物图作为参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`，避免背景图继承绿幕或纯绿色画布。第三步必须以去绿后的敲击物主体图和背景环境图为参考，生成 `1:1` 绿色背景返回按钮图，服务端去绿后写回 `backButtonAsset`。三步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；返回按钮只允许参考图约束圆形底色和箭头配色，不允许继承复杂造型、花纹、浮雕边、异形外框或装饰图案，主体视觉尺寸比当前模板再放大约 50%，并带主题色外描边；背景图不得包含敲击物本体或木槌互动物品，返回按钮图不得包含文字、数字、水印或额外 UI 面板。
+- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为三步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图；`api-server` 先对这张绿幕图执行去绿背景处理并写回 `hitObjectAsset`。第二步必须以第一步抠图完成后的透明敲击物图作为参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`，避免背景图继承绿幕或纯绿色画布。第三步必须以去绿后的敲击物主体图和背景环境图为参考，生成 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景返回按钮图，服务端去绿后写回 `backButtonAsset`。三步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；返回按钮只允许参考图约束圆形底色和箭头配色，不允许继承复杂造型、花纹、浮雕边、异形外框或装饰图案，主体视觉尺寸比当前模板再放大约 50%，并带主题色外描边；背景图不得包含敲击物本体或木槌互动物品，返回按钮图不得包含文字、数字、水印或额外 UI 面板。
 - 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json`、`wooden_fish_work_profile.back_button_asset_json`、shared contracts、前端结果页 / 运行态背景与返回按钮展示、敲木鱼 PRD 和平台链路文档。
 - 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml`、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -1212,7 +1300,7 @@
 ## 2026-05-22 抓大鹅素材生成改为关卡整图派生三图
 
 - 背景：旧抓大鹅素材链路按物品 5x5 sheet、纯背景和独立容器图分开生产，难以保证背景、UI、容器和物品风格一致，也让结果页继续暴露背景 / 容器重生成入口。
-- 决策：抓大鹅草稿生成先用 `gpt-image-2` 无参考图生成竖屏 `9:16` 完整关卡画面；关卡画面完成后，以它作为参考并发生成三张可运行资产：`1K 1:1` UI spritesheet、`1K 9:16` 关卡背景图、`2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都固定要求纯绿色绿幕背景，后端上传 OSS 前扣成真实透明 PNG。物品 spritesheet 固定 `10*10`，每行两种物品、每种五个形态。运行态和编辑器都按 alpha 连通域矩形检测解析 UI 和物品图集，不按固定像素坐标切图。
+- 决策：抓大鹅草稿生成先用 `gpt-image-2` 无参考图生成竖屏 `9:16` 完整关卡画面；关卡画面完成后，以它作为参考并发生成三张可运行资产：`1K 1:1` UI spritesheet、`1K 9:16` 关卡背景图、`2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前扣成真实透明 PNG。物品 spritesheet 固定 `10*10`，每行两种物品、每种五个形态。运行态和编辑器都按 alpha 连通域矩形检测解析 UI 和物品图集，不按固定像素坐标切图。
 - 兼容：新增字段继续存入现有 `generatedItemAssets[].backgroundAsset` / `generatedBackgroundAsset` JSON，不新增 SpacetimeDB schema 字段。历史 `containerImage*` 字段只作兼容；如果它与 `uiSpritesheetImage*` 同源，不得再作为运行态中心容器图。
 - 影响范围：`server-rs/crates/api-server/src/match3d/*`、`server-rs/crates/shared-contracts/src/match3d_*`、`packages/shared/src/contracts/match3dWorks.ts`、`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/services/match3dSpritesheetParser.ts`。
 - 验证方式：执行 `cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/services/match3dSpritesheetParser.test.ts src/services/match3dGeneratedModelCache.test.ts`、`npm run typecheck`、`npm run check:encoding`。
@@ -1884,10 +1972,10 @@
 - 验证方式：VN 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`cargo test -p api-server visual_novel`、`cargo test -p api-server creation_agent_document_input`。
 - 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
 
-## 2026-05-04 历史：曾在仓库 `.hermes/` 中建立团队共享记忆
+## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆
 
 - 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
-- 决策：不共享个人 `~/.hermes`，当时先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills；该路径已被 2026-06-18 的 `docs/project-memory/` 口径取代，当前不再作为长期项目记忆入口。
+- 决策：不共享个人 `~/.hermes`，先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills。
 - 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/shared-memory/`。
 - 验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 `docs/project-memory/shared-memory/` 文件。
 - 关联文档：`.hermes/README.md`、`docs/project-memory/shared-memory/team-conventions.md`。
@@ -2379,3 +2467,127 @@
 - 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、`spacetime-module` 拼图 task 表、`spacetime-client` bindings/facade、前端 API request id 复用和后端架构文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`node scripts/check-server-rs-ddd-boundaries.mjs`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation`、`npm run test -- src/services/apiClient.test.ts`、`npm run check:encoding`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-11 图片画布编辑器作为独立画布工程接入
+
+- 背景：网站需要新增 Lovart 风格图片画布编辑器能力，既要支持素材栏、平移缩放、工具模式、吸附线、元数据窗口和修改结果并排展示，也要能保存当前用户的画布视图、图层布局和资源元数据。
+- 决策：主站新增 `/editor` 对应 `image-editor` 阶段，编辑器作为独立图片画布工程挂在平台壳下，并在创作 Tab 提供入口；工程与资源通过 `editor_project` / `editor_project_resource` 落到 SpacetimeDB，经 `spacetime-client` facade 和 `/api/editor/projects*` BFF 读写。图片生成 / 修改 provider、计费和真实任务进度暂不接入，本期修改结果允许使用 mock 生成资源，但必须按生成资源元数据形状保存。
+- 影响范围：主站路由、平台创作入口、图片画布编辑器组件、editor project API client、`api-server` BFF、`spacetime-client` facade、`spacetime-module` 表 / procedure、后端数据契约文档和前端架构文档。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run test -- src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check`、headless Playwright smoke。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-14 图片画布素材库按账号级持久化
+
+- 背景：图片画布需要 Lovart 式素材管理，素材不应只挂在单个 project 临时状态里；用户在任意项目上传的图片素材，都应作为账号素材库在其它项目中可见，同时画布自身的图层、视图和分组仍属于项目下的画布数据。
+- 决策：新增 `editor_asset_folder` / `editor_asset` 作为账号级素材库表，以 `owner_user_id` 为归属；`editor_project` 继续承载工程元数据，`editor_canvas` 继续承载 project 下的画布视图和图层布局，`editor_project_resource` 继续承载具体画布资源引用。素材库 CRUD 统一经 `spacetime-client` facade 和 `/api/editor/assets*` BFF，前端只保留选择模式、框选、拖拽上传、图层打组和小地图拖拽等交互状态，不直接绕过后端持久化。
+- 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`、后端数据契约文档和图片画布前端技术方案。
+- 验证方式：`npm run spacetime:generate -- --rust-only`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-15 图片画布角色图层新增动画生成入口
+
+- 背景：图片画布已有角色形象图层标记 `assetKind="character"`，需要只对角色图片开放动画生成，不让普通素材误触发角色动画链路。
+- 决策：角色动画入口只由画布图层 `assetKind="character"` 控制，在图片上方浮动工具条和右键菜单显示 `生成动画`；非角色图层不展示入口。点击后打开独立 `角色动画生成面板`，桌面端锚定到图片右侧，移动端按底部面板承接。前端固定提交 `seedance2.0-fast`、分辨率 / 比例 / 帧数 / 时长 / 价格字段；后端经 `/api/editor/character-animations/generations` 使用角色图作为首帧和尾帧生成视频，并立即抽取 32 / 40 / 48 帧、绿幕去背后写入 OSS。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/shared-contracts/src/assets.rs`、图片画布技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-16 图片画布图标素材面板采用 Lovart 式参考卡与横向增宽布局
+
+- 背景：图标素材生成面板里，规范入口与素材描述项过于平铺，且子面板内部采用滑动列表，和 Lovart 风格画布的参考卡 / 物料卡不一致。
+- 决策：`生成图标素材` 面板不使用内部纵向滚动列表；每新增一个素材描述项就让面板整体增宽，保持描述项横向卡片一眼可扫。图标规范入口改为 Lovart 式参考卡：缩略图、名称、绑定状态和轻量动作分区分开呈现，独立菜单只负责来源切换，不再承载说明文案。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/index.css`、图标素材生成专项设计文档。
+- 验证方式：新增或增删素材描述项时，面板宽度应随项数变化；图标规范入口应呈现参考卡视觉而非纯文本按钮；移动端下仍应固定在底部锚定，不出现内部滚动条。
+- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-16 图片画布图标素材与角色生成支持双图片模型
+
+- 背景：图片画布需要一次生成多枚 UI 图标素材，并保证生成后能按用户输入顺序命名、拆成独立透明素材铺回画布；角色形象生成也需要和图标素材共用同一套图片模型选择、比例和大小口径。
+- 决策：底部 `生成图标素材` 入口创建一叠空白图标占位和独立面板；图标规范参考图只允许绑定 `assetKind="icon-spec"`。`生成角色形象` 与 `生成图标素材` 均支持 VectorEngine `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`，用户在两类面板中切换过模型后下一次打开继续沿用上次模型。前端提交 `model`、`aspectRatio`、`imageSize`；后端不再按图标数量分 `512x512/1024x1024`，而是按模型归一尺寸：`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，把参考图写成 `inline_data`，并在 `generationConfig.imageConfig` 写入比例和大小，`0.5K` 传 `"512"`；`gpt-image-2` 无参考图走 generations，有参考图走 edits，按文档支持的 `size` 字符串映射。图标素材仍先生成绿幕 spritesheet，再由 `platform-image` 绿幕去背并按 8 邻域连通域从上到下、从左到右拆分。成品图标图层写入 `assetKind="icon"`，角色图层写入 `assetKind="character"`。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/platform-image/src/vector_engine/*`、`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、图片画布技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p api-server editor_generation_dimensions_follow_model_options --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image nanobanana_generate_content --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-16 图片画布生成面板与浮层层级收口
+
+- 背景：图片画布底部工具栏和角色参考图行都存在局部滚动 / 裁切容器，生成规范菜单和角色规范来源菜单如果仍内嵌在触发按钮附近，会被边界遮挡；同时生成类面板打开后隐藏底部工具栏会破坏连续创作节奏。
+- 决策：`生成规范`、`角色规范来源` 和 `图标规范来源` 菜单统一通过页面级 fixed portal 渲染到 `document.body`，触发按钮只提供定位锚点；点击 `生成工具`、`生成角色形象` 或 `生成图标素材` 后底部 AI 工具栏保持可见。点击画布空白区域只关闭当前生成面板并清除图片选中样式，不删除新建的占位图。角色面板中的 `角色规范` 与 `上传常规参考图` 入口统一改为 Lovart 式参考图卡片。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/index.css`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`、图片画布前端技术方案和角色形象生成设计文档。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-16 图片画布图片信息页不展示生图 Prompt
+
+- 背景：图片画布中每张生成图片的信息页原来展示 `Prompt` 和复制 Prompt，但该字段可能是后端组装后的生图提示词，不适合作为用户可见的图片输入信息。
+- 决策：图片信息页删除生图 Prompt 展示和复制入口，改为展示生成时的用户面板输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、修改要求，以及角色规范、常规参考图、图标规范和修改参考图等参考图卡片。旧数据或上传图片没有输入快照时显示 `-`，不得回退展示内部 Prompt。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、图片画布 layout snapshot、图片画布技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx` 应覆盖图片信息页无 `Prompt`、无 `复制Prompt`，并展示普通生成、角色生成、图标素材和修改结果的输入快照。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-16 图片画布按 Resolution 原分辨率显示
+
+- 背景：图片画布图层曾同时维护展示 `Size` 与资源 `Resolution`，旧布局快照里的 `width/height` 可能把大图缩成小图，导致画布视觉和图片信息里的原始分辨率不一致。
+- 决策：图片图层不再把独立 `Size` 作为用户可见字段或展示真相；画布图层渲染宽高、悬浮尺寸胶囊和图片信息页统一以 `originalWidth/originalHeight`（即 `Resolution`）为准。旧 layout 中的 `width/height` 只作为缺少 Resolution 时的兼容兜底，不再优先决定展示大小。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、图片画布 layout hydrate、新建 / 上传 / 生成 / 快速编辑 / 图标素材生成结果铺回画布逻辑，以及图片画布技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "hydrates canvas images from Resolution instead of saved Size|opens generated image info from the corner button and creates a real right-side edit result|shows image resolution on hover"`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-19 图片画布上传入口按来源区分入画布语义
+
+- 背景：底部工具栏上传入口选择文件后只进入素材库，未创建画布图层；同时上传图层和素材记录先使用固定兜底尺寸，浏览器异步读到图片原始尺寸前已经把错误尺寸持久化。
+- 决策：底部工具栏上传是“上传到画布”入口，选中文件后写入默认素材文件夹并立即在当前画布视口中心创建图层；素材栏文件夹内上传仍只写入目标素材文件夹。上传图片必须在创建占位素材、画布图层和账号级素材记录前解析原图 Resolution，PNG/JPEG/WebP/GIF/BMP 先读文件头，无法解析时才回退浏览器解码或上传兜底尺寸。
+- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasUploadWorkflow.ts`、`src/components/image-editor/ImageCanvasFileModel.ts`、`src/components/image-editor/ImageCanvasUploadModel.ts` 和图片画布技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasFileModel.test.ts src/components/image-editor/ImageCanvasUploadModel.test.ts src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx`、`npm run test -- src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx -t "bottom toolbar uploads|multiple files as account-level assets"`、`npm run typecheck`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-17 图片画布底部生成视频接入 Lovart 面板
+
+- 背景：编辑器画板底部工具栏需要新增 `生成视频`，并和现有 Lovart 式生成类面板、泥点展示、占位图和画布结果图层保持一致。
+- 决策：`生成视频` 点击后创建独立视频生成占位和极简面板，提交 `POST /api/editor/videos/generations`；首期前端仅开放 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，不展示 Veo 模型入口，默认 `seedance2.0-fast`。后端必须严格区分 Seedance 2.0 Fast 与标准版：`seedance2.0-fast` 映射 `doubao-seedance-2-0-fast-260128`，`seedance2.0` 映射 `doubao-seedance-2-0-260128`，不得混用；固定文字转视频、`16:9`、标准模式和静音。后端复用 Ark / VectorEngine content generation task 轮询链路，下载视频后持久化到 OSS。生成结果在画布中写入 `mediaType="video"` 与 `assetKind="video"`，图片信息弹窗按视频显示为 `视频信息` / `视频类型`。生成类泥点价格统一走 `editor_generation_config`：角色动画固定 `seedance2.0-fast` 仍为 480p 每秒 10 / 720p 每秒 20；生成视频按模型分档，`seedance2.0-fast` 为 10 / 20，`seedance2.0` 为 12 / 24，`kling3.0` 为 15 / 30，`kling3.0-omni` 为 20 / 40，Veo 旧布局兼容价为 10 / 20。
+- 影响范围：图片画布生成工作流、前端 editorProjectClient、`shared-contracts`、`api-server` 视频生成 BFF、编辑器技术方案和生成类面板方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "opens the bottom generate video panel"`、`npm run test -- src/components/image-editor/ImageCanvasMetadataModalView.test.tsx`、`npm run test -- src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p shared-contracts editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-17 图片画布生成器快照纳入画布布局
+
+- 背景：生成占位图和生成器对话框里包含用户输入、参数、参考图、占位框位置和生成结果绑定，刷新后丢失会让已生成图片无法回到 Lovart 式跟随编辑状态。
+- 决策：生成器对象统一作为 `editor_canvas` 布局 JSON 的 `itemType: "generation-dialog"` 项保存，不新增表；成功生成后仍保留生成器快照和最后占位框位置，并通过 `generatedLayerId` 锚定到成品图层，渲染时不重复显示灰色占位框。图片类生成结果同步写入账号级素材库；视频结果当前只作为画布视频资源保存。
+- 影响范围：图片画布 layout 序列化 / hydrate、生成工作流、生成器渲染、项目自动保存、素材库回填和编辑器技术方案。
+- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useCanvasGenerationDialogs.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`、浏览器刷新 smoke。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-06-18 编辑器画板音效待生成占位类型化
+
+- 背景：`/editor/canvas` 新建视频、角色形象、音效和背景音乐待生成对象时沿用图片占位 icon，音效面板仍把 `type` 与 `tempo` 分成两个旧字符串选项，不符合 Lovart 式简洁参数按钮和 BPM 输入需求。
+- 决策：画布待生成占位按生成器模式渲染专属空白样式、icon 与右上角标签：视频、角色、音效、背景音乐不再统一使用图片 icon；角标继续按 viewport 反向缩放。原计划中的 `type + tempo/BPM` 音效参数已在 2026-06-19 被 Vidu `prompt + duration` 契约替代，后续不要再恢复 `单次·120BPM` 入口。
+- 影响范围：`src/components/image-editor/ImageCanvasWorldView.tsx`、`ImageCanvasGenerationComposerView.tsx`、`ImageCanvasEditorTypes.ts`、`ImageCanvasGenerationSubmissionModel.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/shared-contracts/src/assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`server-rs/crates/platform-audio/src/request.rs`。
+- 验证方式：`npx vitest run src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasGenerationModel.test.ts src/services/image-editor/editorProjectClient.test.ts --reporter verbose`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_sound_effect --manifest-path server-rs/Cargo.toml`。
+
+## 2026-06-18 图片画布角色动画改为角色动作生成占位
+
+- 背景：旧角色动画入口点击后打开窄侧边面板，和 Lovart 式新建图片 / 视频占位不一致；点击生成好的角色图时也容易被误解为会自动进入重绘或生成面板。
+- 决策：点击已生成角色图只选中图层并显示浮动工具栏，不自动弹出重绘、快速编辑或角色动画面板。点击工具栏或右键菜单的 `生成动画` 后，创建 `mode="character-animation"` 的画布 generation dialog，占位走统一避让落点与视口居中；占位使用角色动作 icon、橙色动作配色和右上角 `动作` 标签。角色动画参数面板复用原内容，但作为统一 generation composer 跟随占位底部，宽度对齐图片生成面板。提交成功后以首帧创建 `assetKind="character-animation"` 的角色动作图片图层，右上角标签显示 `动作`。
+- 影响范围：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`useImageCanvasGenerationSurface.tsx`、`ImageCanvasCharacterAnimationPanelView.tsx`、`ImageCanvasWorldView.tsx`、`ImageCanvasGenerationLayerModel.ts`、`useImageCanvasGenerationSubmissionWorkflow.ts`、`src/index.css`。
+- 验证方式：`npx vitest run src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx --reporter=dot`、`npx vitest run src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "character animation" --reporter=dot`。
+
+## 2026-06-19 编辑器游戏音效默认改用 Vidu 文生音频
+
+- 背景：VectorEngine Apifox `创建文生音频任务` 文档明确 Vidu `/ent/v2/text2audio` 请求体使用 `model: "audio1.0"`、`prompt`、`duration` 和可选 `seed`；编辑器此前把游戏音效提交到 Suno `task: "sound"`，与当前游戏音效默认模型要求不一致。
+- 决策：`/editor/canvas` 的 `生成游戏音效` 入口继续保留，但默认且暂时唯一可用模型为 Vidu `audio1.0`，前端请求固定发送 `prompt`、`model: "audio1.0"`、`duration` 和 `priceMudPoints`，面板只显示 `Vidu` 与 `2-10` 秒时长选项，默认 `5` 秒；不再展示 `type`、`tempo`、BPM 或 Suno 文生音效入口。后端 `/api/editor/audios/sound-effects/generations` 只接受空模型或 `audio1.0`，拒绝 Suno / `chirp-*`；提交到 VectorEngine 时对内 `prompt` 同步映射为上游 body 的 `prompt` 与 `sound`，兼容 Apifox 文档和线上网关实际 `missing field sound` 校验；提交和轮询改走 Vidu `/ent/v2/text2audio` 与 `/ent/v2/tasks/{taskId}/creations`。背景音乐仍保留 Suno `/suno/submit/music`、`/suno/fetch/{taskId}` 和 wav clip 兜底逻辑。
+- 影响范围：`server-rs/crates/platform-audio`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`server-rs/crates/shared-contracts/src/assets.rs`、`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/ImageCanvasGeneration*`。
+- 验证方式：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml --test vector_engine_audio`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_sound_effect`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_audio_requests_and_response_use_canvas_audio_shape`、`npx vitest run src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasGenerationModel.test.ts --reporter=dot`。
+
+## 2026-06-19 角色主图抠图补充内部镂空检测
+
+- 背景：编辑器角色形象和 Big Fish 正式图复用 `character_visual_assets::try_apply_background_alpha_to_png` 的角色主图透明背景后处理；原算法主要从画布四边扩散清理绿幕 / 近白背景，对主体包围的内部绿幕或近白镂空不稳定。
+- 决策：角色主图抠图继续保留在 `api-server` 的 `character_visual_assets` 口径内，不切换到 `platform-image::generated_asset_sheets`。在边缘连通背景 BFS 之后、软边扩展和边缘去污染之前，新增内部背景连通域检测：只清理不触画布边界、像素数达到阈值、且为高置信绿幕 / 近白背景的内部连通域，避免误伤普通角色纹理。
+- 影响范围：`server-rs/crates/api-server/src/character_visual_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml character_background_alpha_removes_internal_green_holes`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_postprocess`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-06-19 编辑器角色形象回填改用通用抠图
+
+- 背景：画板编辑器里的 `生成角色形象` 属于编辑器图片生成链路，用户要求把“人物抠图”改成通用抠图方法，不再与 RPG / 资产工坊角色主图专用后处理绑定。
+- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；输出仍归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
+- 2026-06-22 补充：所有明确设置绿幕用于后续抠图的 prompt 都必须固定写明 `#00FF00 / RGB(0,255,0)`，不能只写“纯绿色绿幕”或“接近 #00FF00”；编辑器角色图通用抠图额外开启暗绿 / 灰绿绿幕背景识别，只作为生成模型偏离标准亮绿时的兜底。该宽松识别只参与从画布边缘连通扩散出的背景清理，不参与全图断开绿色区域删除，避免误伤角色衣物或纹理。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_general_cutout`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet_muted_green_alpha_requires_explicit_option`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 23854b85c..293da2097 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -23,6 +23,142 @@
 - 验证：运行 `npm run check:production-ops`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，确认构建包、Jenkins 归档链路和 deploy fail-fast 检查口径一致。
 - 关联：`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-api-deploy`、`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-ops-guardrails.mjs`。
 
+## 图片画布角色动作结果不能把首帧当主媒体
+
+- 现象：画板里 `生成角色动作` 返回后显示成一张不可播放图片，点击下载或素材 ZIP 导出时拿到的也是 PNG，而不是动作视频。
+- 原因：后端已经生成 `previewVideoPath`，并继续执行抽帧、绿幕去背和帧素材 OSS 落盘；前端落层时却把 `frames[0].imageSrc` 当作图层主 `src`，且没有设置 `mediaType: "video"`，导致预览和导出都按图片处理。
+- 处理：角色动作结果图层主 `src` 必须使用 `previewVideoPath`，`mediaType` 固定为 `video`，`assetKind` 固定为 `character-animation`；首帧透明 PNG 只写入 `thumbnailSrc`，用于 `<video poster>` 和后续动作素材二次生成源。不得移除后端原有视频生成、抽帧、绿幕去背和帧落盘流程。
+- 验证：`ImageCanvasGenerationLayerModel` 应断言动作结果 `src` 为预览视频且 `thumbnailSrc` 为首帧；画布集成测试应出现 `<video controls poster=...>`；导出模型应按 `mediaType="video"` 输出 mp4/webm/mov 等真实视频扩展名。
+- 关联：`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## Vidu 文生音频线上网关可能要求 sound 字段
+
+- 现象：画板点击 `生成游戏音效` 后，请求返回 `Failed to deserialize the JSON body into the target type: missing field sound`。
+- 原因：VectorEngine Apifox `创建文生音频任务` 文档仍写 `/ent/v2/text2audio` 使用 `model + prompt + duration`，但线上 Vidu 网关曾按 `sound` 字段反序列化；只发送 `prompt` 会被上游拦截在 JSON 解析阶段。
+- 处理：前端和 BFF 对内继续使用用户语义更清晰的 `prompt`；`platform-audio` 转发到 VectorEngine Vidu 时同时发送 `prompt` 与 `sound`，两者值保持一致。不要把 UI 改回 Suno `task: "sound"`、`type`、`tempo` 或 BPM。
+- 验证：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml --test vector_engine_audio` 中音效请求体测试必须同时断言 `prompt` 与 `sound`；必要时用线上生成音效 smoke 确认不再出现 `missing field sound`。
+- 关联：`server-rs/crates/platform-audio/src/request.rs`、`server-rs/crates/platform-audio/tests/vector_engine_audio.rs`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
+## Suno 任务完成不代表已经拿到 wav 下载地址
+
+- 现象：画板生成背景音乐时，前端报 `音频生成尚未返回可下载地址(requestId:...)`；画板生成音效时，前端可能报 `获取 Suno 音效 wav 失败(requestId:...)`。上游任务可能已经完成，但 wav 下载地址还没就绪。
+- 原因：VectorEngine Suno `/suno/fetch/{task_id}` 可能先在 `data` 中返回歌曲 / 音效 clip id，而不是直接返回 `.wav` / `.mp3` URL；需要再调用 `/suno/act/wav/{clipId}` 获取 `wav_file_url`。如果只兼容 `data` 是字符串，会漏掉 `data` 对象 / 数组里的 `id`、`clip_id`、`audioId` 或 `songId`。
+- 处理：`platform-audio` 查询 Suno 结果时先提取直接音频 URL；没有 URL 时，从 `data` 字符串、对象或数组提取 clip id，逐个调用 `/suno/act/wav/{clipId}`。已拿到 clip id 但 wav 地址仍未就绪，或 wav 子请求暂时返回上游错误时，都保持 `processing` 让上层继续轮询，不能直接判定为缺少可下载地址或 wav 获取失败。
+- 验证：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`；`cargo test -p api-server vector_engine_audio_generation --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/platform-audio/src/client.rs`、`server-rs/crates/platform-audio/src/response.rs`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
+## 图片画布音频卡播放条 0:00 要优先查签名 URL 和嵌套交互
+
+- 现象：画板音效或背景音乐已经生成成功，但卡片里的播放条显示 `0:00`，点击无法预览。
+- 原因：generated 音频资源通常是私有 OSS 路径，直接把 `/generated-*` 或 generated OSS 地址交给 `<audio>` 会无鉴权读取失败；如果音频控件嵌在 `<button>` 图层里，浏览器还可能因嵌套交互元素阻断 controls 行为。
+- 处理：音频图层使用非嵌套交互容器承接画布选择语义，内部 `<audio controls preload="metadata">` 单独阻止 pointer / click 冒泡；generated 音频播放前统一通过 `useResolvedAssetReadUrl` / `/api/assets/read-url` 换签。卡片和角标展示 `时长`，后端没返回时长时可用 `loadedmetadata.duration` 兜底。
+- 验证：`npx vitest run src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasMetadataModalView.test.tsx src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts --reporter verbose`，并在浏览器确认 generated 音频控件可播放。
+- 关联：`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasMediaModel.ts`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
+## 图片编辑器底部生成按钮不要复用单一画布生成状态
+
+- 现象：图片画布里先新建一个“生成规范”占位，再点击“生成角色形象”或其它底部生成入口，前一个规范占位和面板状态被销毁。
+- 原因：底部普通生成、规范、角色和图标素材曾共用单个 `generateDialog` 状态；后一次点击直接覆盖该状态，等同把前一个画布生成对象卸载。
+- 处理：底部生成类入口每次点击都创建独立 generation dialog id；当前 active 对象只负责显示编辑面板，旧对象归档为 inactive 后仍保留占位和生成逻辑状态。生成完成 / 失败回写、生成中拖拽和删除都必须按 dialog id 读取 active + inactive 中的最新对象，不能回退到提交瞬间的旧占位快照。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps existing generation placeholders"` 应断言规范占位和角色占位可同时存在；`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps archived generation logic"` 应断言旧对象归档后拖动，占位完成回写仍落在最新位置。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片编辑器生成中设定面板不要和预览框绑成同一可见性
+
+- 现象：图片编辑器里点击生成后，有时设定面板没收起，有时连画布上的占位预览一起消失，看起来像“生成中界面掉了”。
+- 原因：生成中状态只收了 composer 可见性，或把占位框和设定面板共用了同一段条件渲染；面板隐藏后把 placeholder 也一起卸掉，就会丢掉 Lovart 式生成中预览。
+- 处理：进入 `generating` 后只隐藏设定面板，保留占位框和生成中状态胶囊；面板外观、预览框和结果图层分开控制，不共用同一个 `composerOpen` 条件。
+- 验证：对应测试应断言生成按钮点击后 `dialog` 消失但 `image-canvas-editor__generation-frame--generating` 仍然存在。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`。
+
+## 图片编辑器宣发素材生成器刷新后不要丢快照
+
+- 现象：图片画布刷新后，宣发素材生成卡片消失，或卡片仍在但游戏名、分类、描述和参考图丢失。
+- 原因：画布布局把生成器保存为 `itemType: "generation-dialog"`，但恢复白名单漏掉 `publication` 模式和 `publicationWorkflowId` / `publicationGameInfo` / `publicationReferences` 字段，导致整条生成器快照被当成无效布局项丢弃。
+- 处理：`hydrateCanvasGenerationDialog` 必须把 `publication` 视为正式画布生成器模式，并显式恢复宣发素材专属字段；组件层应断言刷新回读项目快照后仍显示卡片类型、字段和参考图。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx --reporter verbose`。
+- 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx`、`src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
+
+## 图片画布快速编辑不要直接提交普通图片 URL
+
+- 现象：图片画布快速编辑站内示例图、历史 generated 图或 OSS generated 图时，后端返回 `修改图片参考图必须是图片 Data URL。`。
+- 原因：快速编辑直接把图层 `src` 塞进 `/api/editor/images/generations` 的 `referenceImageSrcs`；默认示例图和部分持久化图层的 `src` 是 `/creation-type-references/*.webp`、`/generated-*` 或 OSS URL，而 `api-server` 的编辑参考图解析只接收 `data:image/*;base64,...`。
+- 处理：前端统一通过 `resolveEditorImageReferenceDataUrl(...)` 在提交前读取图片字节并转成图片 Data URL；Data URL 原样透传，`/generated-*` 和 generated OSS URL 走 `/api/assets/read-bytes` 避免 CORS，普通 public 路径直接 fetch。
+- 验证：`npm run test -- src/services/image-editor/editorImageReference.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx -t "editorImageReference|converts non-data-url quick edit source images before submitting references"`。
+- 关联：`src/services/image-editor/editorImageReference.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片编辑器角色动画不要默认提交大图 Data URL
+
+- 现象：图片编辑器里对角色图点击 `生成动画` 后，后端返回 `Failed to buffer the request body: length limit exceeded`，请求还没进入角色动画 handler。
+- 原因：角色动画生成请求曾把角色图片 `src` 原样作为 `sourceImageSrc` 放进 JSON；角色图如果是较大的 Data URL，会超过 Axum 默认 `2MB` body limit，在 `Json` 提取器阶段被拦截。
+- 处理：前端在角色图已持久化时优先提交 `objectKey`，只把 Data URL 作为未持久化本地临时图兜底；后端 `/api/editor/character-animations/generations` 单独配置 `12MB` body limit 兼容旧请求，但新链路不应依赖传大图 JSON。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "only exposes character animation"`；`cargo test -p api-server editor_character_animation_accepts_character_image_body_above_default_limit --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`server-rs/crates/api-server/src/modules/play_flow.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## 图片编辑器角色动画抽帧不要采到视频尾点
+
+- 现象：画板角色图点击 `生成动画` 后，Ark 视频已生成并上传 OSS，但后端返回 `ffmpeg 已执行但未产出动作帧文件(requestId:...)`。
+- 原因：FFmpeg 在 `-ss` 采样时间落到视频尾点附近时可能退出码仍为 `0`，但实际输出 `0` 帧；如果后端按 `duration - 0.001` 抽最后一帧，低帧率或短视频很容易踩到不可解码尾点。
+- 处理：角色动画抽帧按目标帧数预留一个采样步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，不要采 `3.999s`；`ffmpeg` 返回成功但无输出文件时，错误 details 保留 `targetSeconds`、`stdout`、`stderr` 和输出路径，用户主文案保持简短。
+- 验证：`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`，其中 `editor_character_animation_extracts_final_sample_from_short_video` 应覆盖本机 FFmpeg 8 的 0 帧回归。
+- 关联：`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## 图片编辑器生成长请求完成态必须由后端写入画布
+
+- 现象：画板角色形象等生成请求已经在服务端返回 `200`，OSS 中也已有 `generated-character-drafts/.../image.png`，但用户刷新或页面重载后仍看到旧生成卡片停在“生成中”。
+- 原因：生成是一次长 HTTP 请求，浏览器在请求完成前刷新或重新挂载时会丢失原页面的成功回调；如果完成态只靠前端回调把结果图层写回 `editor_canvas.layers_json`，服务端虽然已经创建 `editor_project_resource` / `editor_asset`，但布局里的 `generation-dialog` 仍可能停在 `status="generating"` 且没有 `generatedLayerId`。如果之后从素材库把同一私有素材加回画布，前端再次创建项目资源时若提交 signed URL / Data URL，还会触发 `413`，进一步阻断资源行绑定。
+- 处理：图片生成提交必须在有项目上下文时携带 `canvasCompletion`（生成器 `dialogId`、标题和占位框）；`api-server` 生成成功并创建资源后，直接读取当前项目布局，只有当前布局仍存在对应生成器时才插入轻量结果图层、把生成器改回 `idle` 并写入 `generatedLayerId`，再沿用后端当前 viewport 保存 layout 并返回最新项目快照。前端只应用该快照刷新显示，不在加载时根据资源行推断完成态；有项目上下文但后端没有返回快照时也不得本地补结果图层。为已有 `objectKey` 的图层创建项目资源时，`imageSrc` 只提交 `/<objectKey>`，不要提交 signed URL / Data URL。
+- 验证：`cargo test -p api-server editor_canvas_generation_completion --manifest-path server-rs/Cargo.toml` 覆盖后端完成态写 layout；`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand` 覆盖前端提交 `canvasCompletion`、应用后端快照、项目加载不推断完成态和 `objectKey` 资源创建不提交大 URL。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片编辑器 Seedance 2.0 参考媒体不要提交视频 Data URL
+
+- 现象：画板生成视频选择 Seedance 2.0 并上传参考视频后，请求体暴涨、可能返回 `413` 或上游拒绝 `video_url.url`；文档示例或测试如果写 `data:video/mp4;base64,...`，后续实现很容易照抄。
+- 原因：火山 Seedance 2.0 参考视频只支持公网 URL 或 `asset://` 素材 ID，项目内画板资源应以 `objectKey` 由后端换签；视频不支持 Base64 / `data:video`，且 50MB 视频转 Base64 后会逼近或超过 64MB 请求体上限。参考音频虽然支持 Base64，但也不能单独输入，且大文件同样不应塞进 JSON。
+- 处理：参考视频 / 音频上传先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认；前端保留 signed URL 做预览，提交生成时优先使用 `objectKey`。后端归一化必须拒绝 `data:video/*`，非 Seedance 模型携带参考字段也必须拒绝；Ark body 显式带 `generate_audio:false`。
+- 验证：`npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`；`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`；`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/services/image-editor/editorReferenceUploadClient.ts`、`src/components/image-editor/useImageCanvasUploadWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 图片编辑器生成类菜单要挂到页面级 portal
+
+- 现象：底部 `生成规范` 菜单、角色面板里的 `角色规范` 来源菜单点击后像没有弹出来，实际被按钮所在的局部滚动容器挡住了。
+- 原因：菜单仍然渲染在底部工具栏或参考图横向滚动行内部，父容器带 `overflow`，弹层无法越出边界；即便挂到 portal，如果菜单根节点的 `pointerdown` 继续冒泡到画布视口，也会先触发画布失焦并卸载面板，导致菜单项 `click` 前消失。
+- 处理：这类轻量菜单统一用页面级 fixed portal 挂到 `document.body`，位置根据触发按钮的 `getBoundingClientRect()` 计算；`PlatformFloatingMenu` 根节点必须阻止 `pointerdown` 冒泡，避免画布清空当前生成面板；底部 AI 工具栏在生成面板打开时仍保持可见，不要整栏隐藏。
+- 验证：测试断言菜单不包含在底部工具栏 / 参考图行里，并且生成面板打开时底部 `AI画布工具栏` 仍存在；规范参考图来源菜单应能通过 portal 点击“从画布中选择 / 上传图片”并写回规范参考图。
+- 关联：`src/components/common/PlatformFloatingMenu.tsx`、`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
+
+## 图片编辑器规范图片面板不要脱离统一生成 shell
+
+- 现象：生成 UI 设计图或新建图标规范时，面板参考图、输入区和底部生成按钮相对生成图片 / 生成角色 / 生成视频错位；图标规范甚至可能缺少首行参考图入口。
+- 原因：规范、UI 设计图等面板虽然都属于生成类入口，但 JSX 和 CSS 曾各自维护 `spec-footer`、局部 field wrapper 或缺省参考区，导致后续改造只覆盖普通图片 / 角色 / 视频，规范图片类面板结构漂移。
+- 处理：生成规范下的角色规范、图标规范、自定义规范，以及生成 UI 设计图，都必须复用 `image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image` 外层 shell；首行统一 `image-canvas-editor__generation-ref`，底部统一 `image-canvas-editor__generation-composer-footer` + `image-canvas-editor__generation-submit`。多字段内容只在中央字段区保持紧凑，不单独发明 footer 或省略参考区。
+- 验证：`npm test -- src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx -t "生成UI设计图|生成规范|visible titles|图标规范|character spec"`。
+- 关联：`src/components/image-editor/ImageCanvasGenerationComposerView.tsx`、`src/index.css`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## 图片编辑器生成占位图在生成中也要使用最新拖拽位置
+
+- 现象：用户在图片编辑器里提交生成后继续拖动画布占位图，预览框可以移动，但生成完成后的真实图片仍落回提交瞬间的旧位置。
+- 原因：生成提交函数闭包里保存了旧的 `dialog.placeholder` 快照；如果完成回包仍用这个快照创建图层，就会丢失生成中期间的拖拽坐标。若 `handleGenerationFramePointerDown` 又按 `status === 'generating'` 拦截，则生成中占位图完全不能拖动。
+- 处理：生成占位图的 pointer down 不因 `generating` 禁止；普通图片、规范图、角色图和图标素材回包创建图层时，都从当前 `generateDialogRef.current.placeholder` 读取最新占位位置，失败后保留的占位图也继续走同一拖拽链路。
+- 验证：`npm test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps the generation placeholder draggable while the image is generating"`。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片画布 Lovart 新生成占位必须避让已有图层和占位
+
+- 现象：用户在画布中心已有图片时继续点击“生成图片 / 生成视频 / 生成规范”等入口，新建的待生成占位压在已有图片或其它待生成占位上；生成完成后看起来像图片被覆盖或丢失。
+- 原因：入口直接把 placeholder 放在当前视口中心，没有把已有图层、隐藏状态和 inactive generation dialog 的占位统一纳入避让计算，也没有在落点确定后把 viewport 平移到新占位中心。
+- 处理：所有会创建 generation dialog 的入口都必须走 `ImageCanvasGenerationPlacementModel`，避让所有 `hidden !== true` 的图层和 active / inactive placeholder；按 32px 世界坐标间距外扩阻挡矩形，在候选点中选择距离当前屏幕中心对应画板位置最近且不重叠的位置，再调用 `centerViewportOnPlacement(...)` 保持缩放只平移。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
+- 关联：`src/components/image-editor/ImageCanvasGenerationPlacementModel.ts`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
+
+## Windows 本地 dev 不要把 RUSTC_WRAPPER 绕过写成 rustc
+
+- 现象：Windows 上执行 `npm run dev:api-server` 时，api-server 在 Cargo 启动阶段失败，日志出现 `error: multiple input filenames provided (first two filenames are ... rustc.exe and -)`，`/healthz` 无法访问。
+- 原因：`server-rs/.cargo/config.toml` 默认配置 `rustc-wrapper = "sccache"`；本地 dev 脚本为了绕过损坏的 sccache 需要覆盖 wrapper。Windows 下如果把 `RUSTC_WRAPPER` 设置为 `rustc`，Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，真实 rustc 把 wrapper 传入的 rustc 路径和 stdin `-` 都当输入文件。
+- 处理：Windows 本地 dev 脚本应把 `RUSTC_WRAPPER` 和 `CARGO_BUILD_RUSTC_WRAPPER` 显式设为空字符串，让 Cargo 覆盖项目配置并直连真实 rustc；Linux 保持 `/usr/bin/env` 绕过 sccache。
+- 验证：`npm run test -- scripts/dev.test.ts -t "Windows 下本地 dev Rust env 用空 wrapper 覆盖项目 sccache"`，并用 `npm run dev:api-server` 拉起后访问实际 api 端口的 `/healthz` 返回 200。
+- 关联：`scripts/dev.mjs`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## Pingora 直连 80/443 不能只改 env
 
 - 现象：`/etc/genarrative/pingora-gateway.env` 已把 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN` 改到 `0.0.0.0:443` / `0.0.0.0:80`，但 `genarrative-pingora-gateway.service` 启动失败，日志出现低端口绑定权限错误。
@@ -491,7 +627,7 @@
 
 - 现象：拼图或抓大鹅运行态解析 UI spritesheet 时，把整张背景图、棋盘格、叶子或装饰图也当作 UI 素材区域，按钮映射错乱；截图里常表现为底部按钮区只剩透明棋盘格或素材碎片。
 - 原因：前端解析依赖 alpha 连通域检测，透明背景是前提；但生图模型收到“透明背景 spritesheet”提示后仍可能输出带实景背景或伪透明棋盘格的普通不透明 PNG，OSS 中保存的图没有真实 alpha。
-- 处理：UI spritesheet 提示词应要求统一纯绿色绿幕背景，而不是让模型直接产透明背景；后端在上传 OSS 前复用 `generated_asset_sheets::apply_generated_asset_sheet_green_screen_alpha(...)` 把绿幕扣成真实透明 PNG，再把透明图写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`。
+- 处理：UI spritesheet 提示词应要求统一单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，而不是让模型直接产透明背景；后端在上传 OSS 前复用 `generated_asset_sheets::apply_generated_asset_sheet_green_screen_alpha(...)` 把绿幕扣成真实透明 PNG，再把透明图写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`。
 - 验证：`cargo test -p api-server puzzle_ui_spritesheet_postprocess_turns_green_screen_transparent --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server puzzle_level_scene_spritesheet_and_background_requests_use_references --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_derived_asset_prompts_match_three_sheet_pipeline --manifest-path server-rs\Cargo.toml`。
 - 关联：`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/match3d/works.rs`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
@@ -499,7 +635,7 @@
 
 - 现象：苹果等主题试玩时，中央敲击物图带明显黑底；背景图中央还可能出现苹果主体，或背景环境图偶发变成纯绿色底，和“中央只叠加 hitObjectAsset”的运行态设定冲突。
 - 原因：gpt-image-2 对“透明底”和“背景只做外围氛围”的遵循不稳定。若 hit object 直接入库，黑底会被当成真实像素展示；若背景 prompt 只有软描述，模型会把主题主体画进中央。第一步为了去背刻意要求绿幕图时，如果第二步参考图或 prompt 没有切断绿幕语义，背景图也可能继承纯绿色画布。
-- 处理：敲木鱼 hit object prompt 固定要求先输出 `1:1` 绿色背景主体图（纯绿色绿幕、单一 `#00FF00` 背景），再由 `api-server` 只对绿幕背景做去绿透明化；不要回到黑底 / 白底 / 透明底 prompt 后再做泛抠图。背景生成必须使用第一步抠图完成后的透明图作为参考图，并在 prompt 中显式禁止继承绿色底色、绿幕底色或纯绿色画布；背景 prompt 还要固定要求中央 40% 主体预留区干净，禁止主题主体、局部特写、轮廓影子、重复元素和主题碎片，只允许外围氛围。不要在背景 prompt 写“木鱼预设在屏幕中央位置”或类似中心主体正向描述，运行态敲击物只能由前端叠放。
+- 处理：敲木鱼 hit object prompt 固定要求先输出 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，再由 `api-server` 只对绿幕背景做去绿透明化；不要回到黑底 / 白底 / 透明底 prompt 后再做泛抠图。背景生成必须使用第一步抠图完成后的透明图作为参考图，并在 prompt 中显式禁止继承绿色底色、绿幕底色或纯绿色画布；背景 prompt 还要固定要求中央 40% 主体预留区干净，禁止主题主体、局部特写、轮廓影子、重复元素和主题碎片，只允许外围氛围。不要在背景 prompt 写“木鱼预设在屏幕中央位置”或类似中心主体正向描述，运行态敲击物只能由前端叠放。
 - 验证：`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`，并用花朵 / 苹果 / 玉米主题跑试玩图确认绿幕被去除、主体未被抠除、背景中央不出现主题主体，背景环境图不再出现纯绿色底。
 - 关联：`server-rs/crates/api-server/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
@@ -888,11 +1024,11 @@
 
 - 现象：点击生成抓大鹅草稿后，页面只提示“服务暂不可用”，或者本地 `npm run dev:api-server` 看似启动但生成接口不可用。
 - 原因：配置缺失类错误通常在后端 `error.details.reason` 中给出具体缺项，前端如果只读 `details.message` 会吞掉原因；本地只配置 `ALIYUN_OSS_BUCKET` / `ALIYUN_OSS_ENDPOINT` 时，旧逻辑还会在启动期构造空 AccessKey 的 OSS 客户端并失败。抓大鹅新链路仍是 2D 生图切割，不需要也不应回退 Rodin/GLB。
-- 处理：前端 API 错误展示优先读取 `details.reason`，再读取 `details.message`，避免底层 `error sending request` 覆盖真正可操作的配置或网络原因；`api-server` 只有在 OSS 四件套齐全时初始化 OSS 客户端，部分缺失只记 warning 并让具体 generated 上传/换签接口返回 `OSS 未完成环境变量配置`。抓大鹅素材、封面和背景生成在调用 VectorEngine 前先预检 OSS，并通过 `details.missingEnv` 列出缺项；真实生成需补齐 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和完整 `ALIYUN_OSS_*` 四件套。抓大鹅 UI spritesheet 和物品 spritesheet 的提示词必须要求纯绿色绿幕背景，后端上传 OSS 前统一扣成透明 PNG，避免运行态 alpha 连通域解析失败。
+- 处理：前端 API 错误展示优先读取 `details.reason`，再读取 `details.message`，避免底层 `error sending request` 覆盖真正可操作的配置或网络原因；`api-server` 只有在 OSS 四件套齐全时初始化 OSS 客户端，部分缺失只记 warning 并让具体 generated 上传/换签接口返回 `OSS 未完成环境变量配置`。抓大鹅素材、封面和背景生成在调用 VectorEngine 前先预检 OSS，并通过 `details.missingEnv` 列出缺项；真实生成需补齐 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和完整 `ALIYUN_OSS_*` 四件套。抓大鹅 UI spritesheet 和物品 spritesheet 的提示词必须要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前统一扣成透明 PNG，避免运行态 alpha 连通域解析失败。
 - 验证：`npm run test -- src/services/apiClient.test.ts` 覆盖 `details.reason`；`cargo test -p api-server state --manifest-path server-rs/Cargo.toml` 覆盖半配置 OSS 不阻断启动；`npm run dev:api-server` 后按实际 `GENARRATIVE_API_PORT` 请求 `/healthz`，不要默认打 `3100`。
 - 关联：`packages/shared/src/http.ts`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`、`docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md`。
 
-2026-05-22 补充：抓大鹅“物品 spritesheet”不再按旧 Gemini `generateContent` / `5*5` sheet 路径排查；当前链路先用 `gpt-image-2` 无参考图生成 `9:16` 关卡整图，再以该关卡整图作为 multipart `image` 参考并发编辑生成 `1K 1:1` UI spritesheet、`1K 9:16` 背景图和 `2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都要求纯绿色绿幕背景，上传 OSS 前通过后端透明化处理写入真实 alpha PNG。
+2026-05-22 补充：抓大鹅“物品 spritesheet”不再按旧 Gemini `generateContent` / `5*5` sheet 路径排查；当前链路先用 `gpt-image-2` 无参考图生成 `9:16` 关卡整图，再以该关卡整图作为 multipart `image` 参考并发编辑生成 `1K 1:1` UI spritesheet、`1K 9:16` 背景图和 `2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，上传 OSS 前通过后端透明化处理写入真实 alpha PNG。
 
 ## 抓大鹅发布按钮要先开发布面板，封面编辑收口到发布面板内
 
@@ -902,11 +1038,11 @@
 - 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`；`npm run typecheck`。
 - 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DResultView.test.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
-## `.hermes` 只放 Hermes 工具资源，不放项目记忆或个人配置
+## `.hermes` 只放共享内容，不放个人 Hermes 配置
 
 - 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
 - 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。
-- 处理：仓库 `.hermes/` 只放 Hermes 专用 skills、plugins 和启用说明；团队共享记忆、计划和 TODO 统一放在 `docs/project-memory/`；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
+- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
 - 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
 - 关联：`.hermes/README.md`。
 
@@ -1570,7 +1706,7 @@
 
 - 现象：修改抓大鹅素材时容易沿用旧 Rodin/GLB 方案，导致新草稿生成耗时变长、进度停在模型阶段，或运行态等待不存在的 GLB。
 - 原因：仓库里保留了 Hyper3D 通用代理和历史模型字段，旧文档也曾要求草稿阶段同步生成 GLB。当前产品口径已经改为 2D 多视角素材。
-- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个形态，单张 `2K 1:1` 物品 spritesheet 固定 `10*10`，每行承载两种物品、每种五个形态，单张最多承载 20 种物品。素材图 prompt 固定要求纯绿色绿幕背景，上传 OSS 前先把整张 spritesheet 绿幕处理为透明 alpha，再由运行态和编辑器按 alpha 连通域解析；`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]`、首图引用或可解析的物品 spritesheet。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
+- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个形态，单张 `2K 1:1` 物品 spritesheet 固定 `10*10`，每行承载两种物品、每种五个形态，单张最多承载 20 种物品。素材图 prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，上传 OSS 前先把整张 spritesheet 绿幕处理为透明 alpha，再由运行态和编辑器按 alpha 连通域解析；`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]`、首图引用或可解析的物品 spritesheet。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
 - 验证：`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`。
 - 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
@@ -2339,6 +2475,14 @@
 - 验证：`npm run test -- src/components/common/CreativeImageInputPanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
 - 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 项目画布跳转不要先写无参画布路由
+
+- 现象：从 `/creation` 最近项目或 `/project` 项目卡进入画布时，浏览器先进入 `/editor/canvas`，随后再进入 `/editor/canvas?projectid=xxx`，导致返回来源页需要点两次。
+- 原因：`App` 传给平台壳的 `setSelectionStage` 会按 stage 自动 `pushAppHistoryPath(resolvePathForSelectionStage(stage))`；如果项目入口先 `setSelectionStage('image-editor')` 再写项目 URL，就会把无参数画布路由塞入 history。
+- 处理：项目入口必须先写入最终 `/editor/canvas?projectid=xxx`，再切 `image-editor` 阶段；`App` 的 stage setter 在当前位置已经解析为 `image-editor` 时不要再补写基础画布路由。
+- 验证：`npm run test -- src/App.test.tsx`；浏览器中从最近项目或项目页打开项目后，后退一次应直接回到 `/creation` 或 `/project`。
+- 关联：`src/App.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`。
+
 ## 统一创作页短表单软键盘打开不要露出黑底
 
 - 现象：小程序 / H5 移动端点击拼图或敲木鱼创作输入框后，输入框和键盘之间出现一大片黑色区域；H5 还会明显弹一下。跳一跳因为按钮区用 `mt-auto` 撑开页面，看起来没有同样问题。
diff --git a/docs/project-memory/shared-memory/project-overview.md b/docs/project-memory/shared-memory/project-overview.md
index 70e692431..10efa6a22 100644
--- a/docs/project-memory/shared-memory/project-overview.md
+++ b/docs/project-memory/shared-memory/project-overview.md
@@ -24,7 +24,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 - 小程序 WebView 外壳：`miniprogram/`。
 - 法律文本：`media/files/user_agreement.md`、`media/files/privacy_policy.md`、`media/files/disclaimer.md`。
 
-移动端一级 Tab：`推荐 / 发现 / 创作 / 草稿 / 我的`。
+移动端一级 Tab：`推荐 / 发现 / 我的`。桌面端导航保留 `创作` 并新增 `项目`，其中 `/creation` 是独立创作工具主页，`/project` 是画布项目入口。
 
 ## 当前后端路线
 
diff --git a/docs/superpowers/plans/2026-06-16-editor-image-model-options.md b/docs/superpowers/plans/2026-06-16-editor-image-model-options.md
new file mode 100644
index 000000000..0d0163b3a
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-16-editor-image-model-options.md
@@ -0,0 +1,146 @@
+# Editor Image Model Options Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让图片画布的“生成角色形象”和“生成图标素材”支持 `nanobanana2` 与 `gpt-image-2`，并按模型提供合法的尺寸比例与大小尺寸选项。
+
+**Architecture:** 前端抽出编辑器图片模型配置，生成面板只保存模型、比例、大小三个轻量状态；后端集中归一模型和尺寸组合，角色图与图标 spritesheet 继续走现有 VectorEngine、去背、OSS 和拆分链路。用户模型偏好用 localStorage 记住，默认 `nanobanana2`。
+
+**Tech Stack:** React + TypeScript + Vitest；Rust Axum api-server；platform-image VectorEngine provider；Markdown 项目文档。
+
+---
+
+## File Structure
+
+- Modify `C:\Genarrative\src\services\image-editor\editorProjectClient.ts`
+  - 扩展图片生成和图标 spritesheet 请求类型，加入 `aspectRatio` 与 `imageSize`。
+  - 默认图标模型改为 `gemini-3.1-flash-image-preview` 对应的 `nanobanana2`。
+- Modify `C:\Genarrative\src\services\image-editor\editorProjectClient.test.ts`
+  - 先补失败测试：角色 / 图标请求会带模型、比例、大小。
+- Modify `C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.tsx`
+  - 增加模型配置、选项归一、localStorage 偏好、角色 / 图标面板字段和提交 payload。
+- Modify `C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.test.tsx`
+  - 先补失败测试：默认显示 nanobanana2，切换模型后比例 / 大小选项变更，并在请求中传递。
+- Modify `C:\Genarrative\server-rs\crates\platform-image\src\vector_engine\request.rs`
+  - 让 `512` 不被 normalize 成非法尺寸，并保留 gpt-image-2 尺寸。
+- Modify `C:\Genarrative\server-rs\crates\platform-image\tests\vector_engine.rs`
+  - 先补失败测试：nanobanana2 0.5K 请求 body 保留 `512`。
+- Modify `C:\Genarrative\server-rs\crates\api-server\src\editor_project.rs`
+  - 扩展请求 DTO，集中校验 `nanobanana2 / gpt-image-2` 与尺寸组合。
+  - 角色生成按模型走 with_model 调用；图标生成按模型和组合选择尺寸。
+- Modify docs:
+  - `C:\Genarrative\docs\【编辑器】画板角色形象生成入口设计-2026-06-15.md`
+  - `C:\Genarrative\docs\【编辑器】画板图标素材生成入口设计-2026-06-15.md`
+  - `C:\Genarrative\docs\technical\【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`
+
+---
+
+### Task 1: Client request contract
+
+**Files:**
+- Modify: `C:\Genarrative\src\services\image-editor\editorProjectClient.ts`
+- Test: `C:\Genarrative\src\services\image-editor\editorProjectClient.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Add tests asserting `generateEditorImage` and `generateEditorIconSpritesheet` serialize `model`, `aspectRatio`, and `imageSize` when supplied.
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run: `npm run test -- src/services/image-editor/editorProjectClient.test.ts -t "image model options"`
+Expected: FAIL because payloads do not include `aspectRatio` / `imageSize`.
+
+- [ ] **Step 3: Minimal implementation**
+
+Extend input types and JSON body builders to include optional `aspectRatio` and `imageSize`; change icon default model constant to `gemini-3.1-flash-image-preview` if not already.
+
+- [ ] **Step 4: Verify green**
+
+Run same test command. Expected: PASS.
+
+### Task 2: Frontend panel state and local preference
+
+**Files:**
+- Modify: `C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.tsx`
+- Test: `C:\Genarrative\src\components\image-editor\ImageCanvasEditorView.test.tsx`
+
+- [ ] **Step 1: Write failing tests**
+
+Add tests for:
+1. opening `生成角色形象` defaults to model `nanobanana2` and shows `尺寸比例` / `大小尺寸`;
+2. switching to `gpt-image-2` limits visible combinations and submits model + mapped size metadata;
+3. icon spritesheet defaults to `nanobanana2` and submits the chosen model.
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "模型|尺寸比例|大小尺寸"`
+Expected: FAIL because current UI has placeholder model button only.
+
+- [ ] **Step 3: Minimal implementation**
+
+Add model option config, dialog fields `imageModel/aspectRatio/imageSize`, localStorage helpers, option buttons/selects, and submit payload wiring.
+
+- [ ] **Step 4: Verify green**
+
+Run same test command. Expected: PASS.
+
+### Task 3: Backend model and dimension normalization
+
+**Files:**
+- Modify: `C:\Genarrative\server-rs\crates\platform-image\src\vector_engine\request.rs`
+- Modify: `C:\Genarrative\server-rs\crates\api-server\src\editor_project.rs`
+- Test: `C:\Genarrative\server-rs\crates\platform-image\tests\vector_engine.rs`
+- Test: existing unit tests inside `editor_project.rs`
+
+- [ ] **Step 1: Write failing tests**
+
+Add tests covering:
+1. `build_vector_engine_image_request_body_with_model("gemini-3.1-flash-image-preview", ..., "512", ...)` keeps `size = "512"`.
+2. editor character model normalization defaults to nanobanana2 and maps `gpt-image-2 + 2:3 + 1K` to `1024x1536`.
+3. icon spritesheet model normalization accepts both models.
+
+- [ ] **Step 2: Run backend tests to verify failure**
+
+Run:
+`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_request_body_can_use_nanobanana2_half_k -- --nocapture`
+`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_project -- --nocapture`
+Expected: FAIL until normalization functions exist.
+
+- [ ] **Step 3: Minimal implementation**
+
+Add constants and helpers:
+- `EDITOR_IMAGE_MODEL_NANOBANANA2 = "gemini-3.1-flash-image-preview"`
+- `EDITOR_IMAGE_MODEL_GPT_IMAGE_2 = "gpt-image-2"`
+- `normalize_editor_image_model`
+- `normalize_editor_generation_dimensions`
+Use with_model calls for character and icon generation responses.
+
+- [ ] **Step 4: Verify green**
+
+Run the same backend tests. Expected: PASS.
+
+### Task 4: Documentation and final checks
+
+**Files:**
+- Modify docs listed above.
+
+- [ ] **Step 1: Update docs**
+
+Document defaults, user preference, model-specific options, and Apifox source URLs.
+
+- [ ] **Step 2: Run focused verification**
+
+Run:
+`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx`
+`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_request_body_can_use_nanobanana2_half_k -- --nocapture`
+`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_project -- --nocapture`
+`npm run typecheck -- --pretty false`
+`npm run check:encoding`
+
+---
+
+## Self-Review
+
+- Spec coverage: covers role generation, icon spritesheet generation, default model, user preference, model-specific dimensions, docs.
+- Placeholder scan: no unresolved placeholders.
+- Type consistency: frontend uses `model/aspectRatio/imageSize`; backend DTO mirrors camelCase fields.
diff --git a/docs/superpowers/plans/【编辑器】图片信息生成输入快照落地计划-2026-06-16.md b/docs/superpowers/plans/【编辑器】图片信息生成输入快照落地计划-2026-06-16.md
new file mode 100644
index 000000000..7d02559bf
--- /dev/null
+++ b/docs/superpowers/plans/【编辑器】图片信息生成输入快照落地计划-2026-06-16.md
@@ -0,0 +1,84 @@
+# 图片信息生成输入快照 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 图片画布编辑器的图片信息页删除生图 Prompt 字段，改为展示图片生成时的面板输入快照，包括文本字段和参考图。
+
+**Architecture:** 在 `CanvasLayer` 上新增轻量 `generationInputs` 前端快照，只保存用户可见输入和参考图摘要；生成成功时从对应面板状态构建快照，随画布 layout JSON 持久化。图片信息弹窗只读取该快照渲染，不回退显示后端组装 Prompt。
+
+**Tech Stack:** React + TypeScript + Vitest + Testing Library；现有 `UnifiedModal`、平台按钮和图片画布 layout snapshot。
+
+---
+
+### Task 1: 信息弹窗行为测试
+
+**Files:**
+- Test: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+  - 修改已有图片信息测试，断言弹窗不出现 `Prompt` 和 `复制Prompt`。
+  - 新增普通生成图片测试：生成后打开信息页，应显示 `生成输入`、`生成提示词` 和用户输入值。
+  - 新增角色生成图片测试：绑定角色规范参考图后生成，信息页应显示 `角色设定`、`角色规范` 与参考图名称。
+  - 新增图标素材生成测试：绑定图标规范后生成，信息页应显示 `素材描述`、具体描述和 `图标规范` 参考图。
+
+- [ ] **Step 2: Run test to verify it fails**
+  - Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
+  - Expected: FAIL because `generationInputs` is not yet implemented and old `Prompt` field still exists.
+
+### Task 2: 生成输入快照模型与持久化
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.tsx`
+
+- [ ] **Step 1: Add minimal types**
+  - Add `CanvasGenerationInputField`, `CanvasGenerationInputReference`, `CanvasGenerationInputs`.
+  - Add optional `generationInputs` to `CanvasLayer`.
+
+- [ ] **Step 2: Serialize and hydrate**
+  - Include `generationInputs` in `serializeLayer`.
+  - Hydrate only trusted shapes: string `title`, string `value`, string `label`, string `src`.
+
+### Task 3: Build snapshots when creating generated layers
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.tsx`
+
+- [ ] **Step 1: Add builders**
+  - `buildGenerationInputsForImagePrompt(prompt)`.
+  - `buildGenerationInputsForSpec(specType, specValues)`.
+  - `buildGenerationInputsForCharacter(prompt, specRef, references)`.
+  - `buildGenerationInputsForIcon(iconDescriptions, iconSpecRef)`.
+  - `buildGenerationInputsForEdit(prompt, sourceLayer)`.
+
+- [ ] **Step 2: Attach snapshots**
+  - Pass `generationInputs` into `addGeneratedResultLayer`, `addQuickEditResultLayer`, and `addIconSpritesheetResultLayers`.
+  - Keep old `prompt/actualPrompt` for backend metadata and backward compatibility, but do not render them in UI.
+
+### Task 4: Render image info without生图 Prompt
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.tsx`
+- Modify: `C:/Genarrative/src/index.css` if existing metadata styles need a reference grid helper.
+
+- [ ] **Step 1: Replace Prompt row**
+  - Remove `Prompt` dt/dd and `复制Prompt` button.
+  - Render `生成输入` row.
+
+- [ ] **Step 2: Render fields and references**
+  - If `generationInputs` has fields, render each field title/value.
+  - If it has references, render thumbnail cards with title and image.
+  - If both empty or absent, render `-`.
+
+### Task 5: Documentation and verification
+
+**Files:**
+- Modify: `C:/Genarrative/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`
+
+- [ ] **Step 1: Update documentation**
+  - Add note: image info displays panel input snapshot and references, never assembled generation Prompt.
+
+- [ ] **Step 2: Run verification**
+  - Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
+  - Run: `npm run typecheck`
+  - Run: `npm run check:encoding`
+  - Run: `git diff --check`
diff --git a/docs/superpowers/plans/【编辑器】图片画布生成对象独立化修复计划-2026-06-16.md b/docs/superpowers/plans/【编辑器】图片画布生成对象独立化修复计划-2026-06-16.md
new file mode 100644
index 000000000..39ba3f084
--- /dev/null
+++ b/docs/superpowers/plans/【编辑器】图片画布生成对象独立化修复计划-2026-06-16.md
@@ -0,0 +1,106 @@
+# 图片画布生成对象独立化修复 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
+
+**Goal:** 修复图片画布底部生成按钮复用单一状态导致后创建对象销毁前一个对象的问题。
+
+**Architecture:** 保留现有图片画布组件结构，先以回归测试锁定“规范占位 + 角色占位可并存”。实现上把生成占位状态从单个 `generateDialog` 扩展为 active dialog + inactive dialog 列表；每次新建生成对象只新增一个 dialog 实例，旧实例保留占位和逻辑状态，只有当前 active 实例渲染编辑面板。
+
+**Tech Stack:** React、TypeScript、Vitest、Testing Library。
+
+---
+
+### Task 1: 补充失败回归测试
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.test.tsx`
+
+- [x] **Step 1: Write the failing test**
+
+在 `keeps the bottom AI toolbar visible while generation panels are open` 附近新增测试：
+
+```tsx
+it('keeps existing generation placeholders when another bottom generation object is created', () => {
+  render(<ImageCanvasEditorView />);
+
+  const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+  fireEvent.click(
+    within(bottomToolbar).getByRole('button', { name: '生成规范' }),
+  );
+  fireEvent.click(screen.getByRole('menuitem', { name: '角色规范' }));
+
+  expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
+  expect(screen.getByRole('dialog', { name: '生成规范' })).toBeTruthy();
+
+  fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+
+  expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
+  expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+  expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+});
+```
+
+- [x] **Step 2: Run test to verify it fails**
+
+Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps existing generation placeholders"`
+
+Expected: FAIL because only the latest placeholder remains.
+
+### Task 2: 实现最小独立生成对象状态
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.tsx`
+
+- [x] **Step 1: Add stable dialog ids and inactive dialog state**
+
+Add `id: string` to `GenerateDialogState`; add `generationDialogCounterRef`; add `inactiveGenerateDialogs` state. Provide helpers to create ids, archive current active dialog before replacing it, update active/inactive dialogs by id, and list all canvas generation dialogs.
+
+- [x] **Step 2: Update bottom generation openers**
+
+Change `openGenerateDialog`、`openSpecDialog`、`openCharacterGenerationDialog`、`openIconGenerationDialog` so each call archives the current active canvas generation dialog and sets a newly created active dialog. Edit modal remains single active dialog and does not archive.
+
+- [x] **Step 3: Render all placeholders**
+
+Replace the single placeholder render block with a map over inactive dialogs plus active dialog. Only active dialog shows composer; inactive dialogs remain visible and can be clicked to reactivate their own panel.
+
+- [x] **Step 4: Keep actions scoped to active dialog**
+
+Keep submit/update/upload/pick actions operating on active dialog only. Adjust delete, drag, blur, and generated-layer cleanup so they update or remove only the matching active/inactive dialog.
+
+- [x] **Step 5: Keep archived async generation writeback scoped by dialog id**
+
+当一个生成对象已经进入 `generating`，随后用户再创建第二个生成对象并把第一个对象归档为 inactive 时，第一个对象仍可能继续被拖拽或等待异步完成。完成回写必须按 `dialog.id` 从 active + inactive 的最新状态读取占位图，不能使用提交瞬间的旧 `placeholder` 快照。
+
+回归测试：
+
+```bash
+npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps archived generation logic"
+```
+
+### Task 3: 验证并更新文档
+
+**Files:**
+- Modify: `C:/Genarrative/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`
+- Optional Modify: `C:/Genarrative/.hermes/shared-memory/pitfalls.md`
+
+- [x] **Step 1: Run focused tests**
+
+Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "keeps existing generation placeholders|opens character spec generation form|opens icon asset generation panel|removes the active character generation placeholder"`
+
+Expected: PASS.
+
+- [x] **Step 2: Run full image editor test**
+
+Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
+
+Expected: PASS.
+
+- [x] **Step 3: Run encoding check**
+
+Run: `npm run check:encoding`
+
+Expected: PASS.
+
+- [x] **Step 4: Document behavior**
+
+Add one sentence to the image canvas editor technical plan: bottom generation buttons create independent canvas generation objects; creating a new one must not destroy previous placeholders or generated-object logic.
diff --git a/docs/superpowers/plans/【编辑器】画板角色动画生成实施计划-2026-06-15.md b/docs/superpowers/plans/【编辑器】画板角色动画生成实施计划-2026-06-15.md
new file mode 100644
index 000000000..1416c67c7
--- /dev/null
+++ b/docs/superpowers/plans/【编辑器】画板角色动画生成实施计划-2026-06-15.md
@@ -0,0 +1,128 @@
+# 画板角色动画生成 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在图片画布编辑器中，仅对角色图片提供角色动画生成入口，并通过后端 seedance2.0-fast 链路生成视频、抽帧、去绿幕并持久化到 OSS。
+
+**Architecture:** 前端在 `ImageCanvasEditorView` 中基于图层 `assetKind === "character"` 控制悬浮按钮和右键菜单，打开锚定到图片右侧的独立动画生成面板。前端 service 调用新增编辑器角色动画 API，后端复用 `character_animation_assets.rs` 中现有视频生成、抽帧、绿幕去背、OSS 写入能力，避免新建平行资产系统。
+
+**Tech Stack:** React + TypeScript + Vitest；Rust Axum `api-server`；现有 `shared-contracts` 资产 DTO；Aliyun OSS 资产持久化；VectorEngine/Ark seedance2.0-fast 角色动画链路。
+
+---
+
+### Task 1: 文档补充
+
+**Files:**
+- Modify: `C:/Genarrative/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`
+
+- [ ] **Step 1: 补充角色动画生成章节**
+  - 明确仅 `assetKind: "character"` 图层展示入口。
+  - 明确右侧独立面板字段、预设动作、价格、模型、抽帧和 OSS 存储口径。
+  - 明确非角色图层不展示按钮。
+
+- [ ] **Step 2: 运行编码检查**
+  - Run: `npm run check:encoding`
+  - Expected: PASS 或仅与本任务无关的既有问题。
+
+### Task 2: 前端失败测试
+
+**Files:**
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.test.tsx`
+- Modify: `C:/Genarrative/src/services/image-editor/editorProjectClient.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试角色图层显示悬浮 / 右键 `生成动画`。
+  - 测试非角色图层不显示 `生成动画`。
+  - 测试面板提交请求包含 `sourceLayerId`、`sourceImageSrc`、prompt、resolution、ratio、frameCount、durationSeconds、priceMudPoints、model。
+
+- [ ] **Step 2: 验证 RED**
+  - Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`
+  - Expected: FAIL，失败原因是功能/API 尚未实现。
+
+### Task 3: 前端实现
+
+**Files:**
+- Modify: `C:/Genarrative/src/services/image-editor/editorProjectClient.ts`
+- Modify: `C:/Genarrative/src/components/image-editor/ImageCanvasEditorView.tsx`
+- Modify: `C:/Genarrative/src/index.css`
+
+- [ ] **Step 1: 新增 service 类型和请求函数**
+  - `generateEditorCharacterAnimation(input)` 调用 `/api/editor/character-animations/generations`。
+  - 限定 model 固定为 `seedance2.0-fast` 的回包展示字段。
+
+- [ ] **Step 2: 扩展图层 assetKind**
+  - `CanvasLayer.assetKind` 支持 `'character' | 'spec' | null`。
+  - hydrate / serialize / 图片类型展示跟随扩展。
+
+- [ ] **Step 3: 加入口和面板**
+  - 角色图层悬浮工具条和右键菜单显示 `生成动画`。
+  - 面板锚定图片右侧，字段按设计实现，文本框 maxLength=4000。
+  - 价格通过 `resolution * durationSeconds` 计算。
+
+- [ ] **Step 4: 验证 GREEN**
+  - Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`
+  - Expected: PASS。
+
+### Task 4: 后端失败测试
+
+**Files:**
+- Modify: `C:/Genarrative/server-rs/crates/shared-contracts/src/assets.rs`
+- Modify: `C:/Genarrative/server-rs/crates/api-server/src/character_animation_assets.rs`
+- Modify: `C:/Genarrative/server-rs/crates/api-server/src/modules/play_flow.rs` 或现有 editor router 文件（按现有路由事实选择）
+
+- [ ] **Step 1: 写 DTO / prompt / plan 单测**
+  - 验证请求 480p/720p、32/40/48 帧、比例枚举、模型固定 seedance2.0-fast。
+  - 验证构造 prompt 包含用户给定固定骨架与动作描述。
+  - 验证价格计算：480p 每秒 10，720p 每秒 20。
+
+- [ ] **Step 2: 验证 RED**
+  - Run: `cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`
+  - Expected: FAIL，失败原因是 helper 或 handler 尚未实现。
+
+### Task 5: 后端实现
+
+**Files:**
+- Modify: `C:/Genarrative/server-rs/crates/shared-contracts/src/assets.rs`
+- Modify: `C:/Genarrative/server-rs/crates/api-server/src/character_animation_assets.rs`
+- Modify: `C:/Genarrative/server-rs/crates/api-server/src/modules/play_flow.rs` 或现有 editor router 文件
+
+- [ ] **Step 1: 新增编辑器角色动画 DTO**
+  - 请求字段：sourceLayerId/sourceImageSrc/promptText/resolution/ratio/frameCount/durationSeconds/sourceWidth/sourceHeight。
+  - 响应字段：taskId/model/prompt/previewVideoPath/frames/priceMudPoints。
+
+- [ ] **Step 2: 新增 handler**
+  - 校验 prompt 1..4000、resolution、ratio、frameCount 与 durationSeconds 组合。
+  - sourceImageSrc 作为首尾帧参考。
+  - 调用现有 seedance image-to-video 逻辑生成预览视频。
+  - 调用现有抽帧 + 绿幕去背 + OSS 持久化逻辑输出帧。
+
+- [ ] **Step 3: 路由接入**
+  - `POST /api/editor/character-animations/generations`。
+  - 保持走 play_flow 创作/游玩支撑主干或 editor 路由现有聚合，不回到 `app.rs` 平行挂载。
+
+- [ ] **Step 4: 验证 GREEN**
+  - Run: `cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`
+  - Expected: PASS。
+
+### Task 6: 总验证与收口
+
+**Files:**
+- All modified files.
+
+- [ ] **Step 1: 定向前端测试**
+  - Run: `npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`
+  - Expected: PASS。
+
+- [ ] **Step 2: 定向后端测试 / check**
+  - Run: `cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`
+  - Run: `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
+  - Expected: PASS。
+
+- [ ] **Step 3: 类型与编码**
+  - Run: `npm run typecheck`
+  - Run: `npm run check:encoding`
+  - Expected: PASS。
+
+- [ ] **Step 4: 检查 diff**
+  - Run: `git diff --check`
+  - Expected: PASS。
diff --git a/docs/technical/【前端架构】图片画布素材导出方案-2026-06-15.md b/docs/technical/【前端架构】图片画布素材导出方案-2026-06-15.md
new file mode 100644
index 000000000..f35031445
--- /dev/null
+++ b/docs/technical/【前端架构】图片画布素材导出方案-2026-06-15.md
@@ -0,0 +1,158 @@
+# 图片画布素材导出方案
+
+日期：2026-06-15
+
+## 背景
+
+`/editor/canvas` 已承载项目画布、账号级素材库、生成图片、图层、分组、隐藏、锁定、翻转、缩放和右键菜单等编辑能力。用户需要一次性下载当前画布中使用到的全部素材，用于本地归档、外部编辑或跨工具交接。
+
+素材导出应作为画布级能力，而不是单个图层的“导出为”。单图导出仍保留在目标右键菜单；全部素材导出放在画布标题栏，入口稳定、可发现且不打断画布操作。
+
+## 入口设计
+
+- 在画布右上角标题栏内增加下载图标按钮。
+- 图标使用 `lucide-react` 的 `Download`。
+- 按钮 `aria-label` 使用 `下载画布素材`。
+- 入口与返回项目页、项目名称同属标题栏，但视觉上靠右，不进入左下角画布工具组，也不进入底部 AI 工具栏。
+- 标题栏空间不足时，下载图标保持固定尺寸，项目名称使用省略号收缩。
+
+## 第一版范围
+
+第一版实现“导出画布素材 ZIP”：
+
+- 导出当前画布中有效图层引用的图片。
+- 包含上传图、生成图、修改生成结果。
+- 默认包含隐藏图层。
+- 跳过已被素材库删除且已判定无效的上传图层。
+- 锁定、分组、翻转等状态不影响图片文件导出，但写入元数据。
+- 空画布时按钮置灰，或点击后显示轻提示。
+
+暂不实现：
+
+- 画布整体截图 PNG。
+- PSD / Figma / 工程包导出。
+- 后端异步打包任务。
+- 导入导出包恢复画布。
+
+## ZIP 结构
+
+导出文件名：
+
+```text
+项目名-画布素材-YYYYMMDD.zip
+```
+
+包内结构：
+
+```text
+项目名-画布素材/
+├─ images/
+│  ├─ 001-拼图素材.png
+│  ├─ 002-生成图片.png
+│  └─ 003-修改结果.png
+├─ metadata.json
+└─ manifest.txt
+```
+
+## 元数据结构
+
+`metadata.json` 记录项目、导出时间、图层和图片文件映射：
+
+```json
+{
+  "projectId": "editor-project-default",
+  "projectTitle": "默认项目",
+  "exportedAt": "2026-06-15T00:00:00.000Z",
+  "layers": [
+    {
+      "layerId": "layer-generated-1",
+      "title": "生成图片 1",
+      "file": "images/002-生成图片.png",
+      "width": 1024,
+      "height": 1024,
+      "canvas": {
+        "x": 120,
+        "y": 80,
+        "width": 420,
+        "height": 420,
+        "zIndex": 12,
+        "hidden": false,
+        "locked": false,
+        "flipX": false,
+        "flipY": false,
+        "groupId": null
+      },
+      "sourceType": "generated",
+      "prompt": "一张明亮的拼图主视觉",
+      "actualPrompt": "一张明亮的拼图主视觉",
+      "model": "gpt-image-2",
+      "provider": "VectorEngine",
+      "taskId": "editor-real-task-1"
+    }
+  ]
+}
+```
+
+`manifest.txt` 用于人工快速查看：
+
+```text
+项目：默认项目
+导出时间：2026-06-15T00:00:00.000Z
+素材数量：3
+图层数量：5
+```
+
+## 去重规则
+
+同一张图片被多个图层引用时，只导出一份图片，所有图层在 `metadata.json` 中指向同一个 `file`。
+
+图片去重 key 优先级：
+
+```text
+assetObjectId > objectKey > sourceAssetId > src
+```
+
+文件命名按图层 zIndex 从低到高排序，遇到重复名称追加序号。
+
+## 前端实现
+
+第一版优先使用客户端 ZIP：
+
+1. 从当前 `layers` 取目标图层。
+2. 过滤无效图层，保留隐藏图层。
+3. 按去重 key 合并图片源。
+4. 对每个图片源读取 Blob：
+   - `data:image/...` 直接转换为 Blob。
+   - 同源或可访问 URL 使用 `fetch` 拉取 Blob。
+   - 拉取失败时记录失败项，不中断整个导出。
+5. 使用 `JSZip` 写入 `images/`、`metadata.json` 和 `manifest.txt`。
+6. `zip.generateAsync({ type: 'blob' })` 生成文件。
+7. 用临时 `<a download>` 触发下载。
+
+若当前仓库未安装 `jszip`，新增依赖时应只引入 `jszip`，不引入额外下载库。
+
+## 错误处理
+
+- 空画布：按钮置灰或显示短提示。
+- 部分图片下载失败：ZIP 仍生成，`metadata.json` 记录失败图片，UI 显示“部分素材未能导出”。
+- 全部图片失败：不下载 ZIP，显示失败提示。
+- 浏览器不支持 Blob 下载：显示失败提示。
+
+## 测试计划
+
+- 标题栏右上角显示 `下载画布素材` 图标入口。
+- 空画布时入口不可执行或提示为空。
+- 上传图和生成图都写入 ZIP。
+- 多图层引用同一素材时，图片文件只写一份。
+- 隐藏图层默认写入 `metadata.json`。
+- 图层的锁定、翻转、分组状态写入元数据。
+- `data:image` 图片不经过网络请求即可导出。
+- URL 图片 fetch 失败时不中断其他素材导出。
+
+## 后续扩展
+
+- 导出当前选中素材。
+- 导出画布快照 PNG。
+- 导出可恢复工程包。
+- 导入工程包恢复画布。
+- 后端异步打包大项目，前端只轮询下载结果。
diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
new file mode 100644
index 000000000..b27a1be23
--- /dev/null
+++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
@@ -0,0 +1,120 @@
+# 图片画布编辑器 Lovart 化与持久化接入方案
+
+## 背景
+
+网站需要新增一个面向图片素材的独立 `/editor/canvas` 画布入口。第一阶段已经提供纯前端画布体验，本轮把它升级为 Lovart 风格的 AI 图片画布：支持更接近专业画布的拖拽、缩放、吸附、工具模式、元数据查看和图片修改结果并排展示，同时补上工程、画布与资源持久化。
+
+## V2 边界
+
+- 主站新增 `/editor/canvas` 路由，进入独立图片画布编辑器阶段。
+- 主站新增 `/project` 项目页，从“我的”页项目入口进入，展示当前用户所有图片画布工程；点击项目进入 `/editor/canvas?projectid=<projectId>`。
+- 创作 Tab 顶部提供编辑器入口，入口只负责跳转，不参与玩法创作链路。
+- 编辑器左侧为图片素材栏，可展开 / 收起；移动端优先保持素材栏可折叠。
+- 中央画布支持背景拖拽平移、滚轮缩放、缩放百分比菜单、显示所有元素和固定比例缩放。
+- 画布左下角提供 Lovart 式状态控件：背景色圆点、素材 / 图层入口、小地图开关；小地图显示图层缩略分布和当前视口框，点击小地图执行显示所有元素。
+- 画布中的图片可展示、悬浮显示图片 Resolution 尺寸与边框，点击后在图片上方显示浮动工具栏；浮动工具栏只保留当前可执行的编辑动作，不放调整 / 复制 / 删除 / 查看信息占位按钮。图片右上角素材类型标签、图片信息角标和悬浮尺寸标签在画布缩小时必须按 viewport 反向缩放，保持屏幕可读尺寸；无 `assetKind` 的素材右上角显示 `未知` 标签，点击标签弹出独立标签选择菜单并可写回图层 `assetKind`，不能触发图层选择 / 拖拽事件；图片信息角标使用圆形 `i` 图标，不使用中括号或花括号样式。图片不再维护独立展示 `Size` 字段，画布显示宽高统一取 `originalWidth/originalHeight`（图片信息中的 `Resolution`）。
+- 默认工具为选择模式；底部工具栏采用 AI 画布工作流工具组：选择、抓手、上传、生成图片、生成视频、生成音乐、生成规范、生成角色形象、生成图标素材、生成 UI 设计图。底部栏不再展示文字工具、形状标注工具和导出工具；上传与生成图片之间、生成音乐与生成规范之间各有一个半图标高度分割线。
+- 鼠标中键拖拽始终平移画布；长按 Space 临时进入抓手模式，松开后恢复原工具。
+- 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层、生成占位框或画板的边缘与中心线；当移动元素接近两个同轴元素形成的等距位置时，支持横向或纵向等距吸附。
+- 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、快速编辑提示词、重绘提示词，以及角色规范 / 常规参考图 / 图标规范 / 编辑参考图等参考图卡片。参考图输入快照只保存 `refType/refId` 行引用，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`；不得把图片 Data URL、普通 URL 或 `objectKey` 写入 `generationInputs.references`。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。
+- 对生成资源执行重绘时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图；重绘面板不因提交成功自动关闭，便于连续改提示词。
+- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和重绘保留既有 `gpt-image-2` 路径；图片快速编辑默认从原图模型和分辨率初始化，但提交使用面板当前选择的 `model/aspectRatio/imageSize`；其中生成规范类图片固定 `16:9`、`2K`、`gpt-image-2`，面板底部用与可编辑面板一致的比例 / 尺寸 / 模型胶囊按钮展示固定参数，但按钮为禁用态，不允许在该面板改比例、尺寸或模型。`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。宣发素材必须按 workflow 同时提交 `outputSize`、`aspectRatio` 和 `imageSize`，其中游戏首图为 `720x540 / 4:3`、详情单图为 `720x1280 / 9:16`、运营海报为 `1280x720 / 16:9`；生成回填图层优先使用生成占位的 `originalWidth/originalHeight`，即使上游回包尺寸漂移也不得把宣发素材卡片变成随机 `1:1` 或 `4:3`。纯文本生成走 `/api/editor/images/generations`，重绘在前端读入当前图层图片 Data URL 后走同一图片生成 BFF，并在原图右侧生成一张新图；普通图层重绘作为 `quick-edit` 参考图提交，角色图层重绘必须按 `kind: "character"` 提交，继续套用角色生成器提示词限定、透明 PNG 后处理和角色资产持久化。`生成视频` 走 `/api/editor/videos/generations`，前端模型入口仅展示 Seedance 2.0 Fast / Seedance 2.0 / Kling 3.0 / Kling 3.0 Omni，不展示 Veo 入口，默认 Seedance 2.0 Fast；视频参数按当前正式面板支持的比例、时长、清晰度和声音开关提交，且 Seedance Fast 与 Seedance 标准版必须按各自真实模型 ID 独立映射，不得混用。生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成图片后以当前视口世界中心为目标，经统一 placement 避让后创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。图片快速编辑和重绘在调用图片 BFF 前必须把当前图层图片源读取为图片 Data URL；视频素材快速编辑走视频生成 BFF，不允许走图片模型；角色动作快速编辑固定使用 `seedance2.0-fast` 动作 / 视频模型。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
+- 快速编辑面板对齐其它生成类面板：首行支持额外参考图，最多 8 张；原图 / 原素材自动作为最后一张隐式参考提交，但不在参考图条里固定展示 `图x`。尺寸和模型默认从原素材配置 / 分辨率推断，底部参数胶囊可点击修改；图片快速编辑左下角统一显示 `x:y·xK`，右下角模型胶囊紧贴生成按钮。提交前将提示词里对原素材的 `原图`、`当前图片`、`当前图` 或 `图1` 引用改写为最后一张源素材编号，例如额外 1 张参考图时写成 `图2`。点击快速编辑生成后立即创建独立 `Quick Edit Generator` 画布占位播放生成中动画，不再在原图图层上播放生成中遮罩；该生成中占位可通过键盘 `Delete` / `Backspace` 删除。
+- 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。
+- 所有会新建画布生成占位的入口必须先创建 draft，再统一经过 `ImageCanvasGenerationPlacementModel` 计算落点，禁止各入口自行使用当前视口中心裸坐标。当前覆盖入口包括 `生成图片`、`生成规范`、`生成角色形象`、`生成图标素材`、`生成视频`、`生成UI设计图` 和 `生成角色动作`。placement 模型的避让对象为所有未隐藏画布图层，以及当前 active / inactive generation dialogs 中仍存在的 placeholder；每个避让矩形按 32px 画布世界坐标间距外扩。候选落点以当前视口世界中心为距离目标，优先选择离视口中心最近且不重叠的占位位置；若中心被占用，会按上下左右和环形候选继续寻找。打开生成面板时必须把避让后的 placeholder 写入 `openCanvasGenerationDialog(...)`，并立即调用 `centerViewportOnPlacement(...)` 居中到新占位中心，保持原 viewport scale 不变。
+
+## 交互规则
+
+- `适合视图` 的正式语义为“显示画布所有可见元素”，不再回到固定 `x/y/scale`。
+- 右上角缩放控件只展示当前缩放百分比；点击后弹出菜单：放大、缩小、显示画布所有元素、缩放至 50%、缩放至 100%、缩放至 200%。
+- 缩放菜单支持 `Ctrl/Cmd +`、`Ctrl/Cmd -` 和 `Shift + 1`；快捷键只改变 viewport，不修改工程资源。
+- 背景色控件只修改编辑器工作区底色，不恢复网格线或棋盘格底纹，也不影响图片本体。
+- 吸附阈值以屏幕像素为准，换算到世界坐标后参与拖拽计算；边缘 / 中心线和等距吸附共用同一阈值。拖拽结束后只保存最终图层或生成占位布局，不保存临时参考线。
+- 画布自动保存使用防抖策略：图层拖拽、缩放、资源新增和修改结果创建后延迟保存工程快照。
+- 移动端保留同一套状态模型，底部工具栏可横向滚动，侧边栏默认可收起。
+- 项目页卡片默认点击打开工程；hover 项目卡片右下角显示 `...` 菜单，菜单承载重命名和删除。选择模式下项目卡片只切换选中态，不进入画布；底部批量工具栏提供全选 / 取消全选、已选数量、批量删除和退出选择模式。
+
+## 数据与持久化
+
+- 新增 `editor_project` 表保存图片画布工程：`projectId`、`ownerUserId`、标题、创建时间和更新时间；历史 layout 字段暂保留为兼容列，不再作为权威画布数据。
+- 新增 `editor_canvas` 表保存工程下的画布：`canvasId`、`projectId`、`ownerUserId`、标题、viewport、图层布局 JSON、创建时间和更新时间。当前编辑器使用项目默认画布，后续可扩展为一个 project 下多个 canvas。
+- 新增 `editor_asset_folder` 表保存账号级素材文件夹：`folderId`、`ownerUserId`、名称、排序、折叠状态、系统默认标记、创建时间和更新时间。素材文件夹不归属于 project，同一个账号进入任一项目都能看到。
+- 新增 `editor_asset` 表保存账号级素材：`assetId`、`ownerUserId`、`folderId`、名称、图片读取地址、OSS / asset object 引用、图片尺寸、来源类型、prompt、actualPrompt、model、provider、taskId、`assetKind`、`generationInputs`、创建时间和更新时间。素材只跟账号走，不跟 project 走；角色、图标、UI 设计图、视频和音频等生成结果的用户可见输入快照随素材保存。
+- `editor_project_resource` 表保存工程画布引用过的资源快照：`resourceId`、`projectId`、`ownerUserId`、OSS / asset object 引用、图片尺寸、来源类型、prompt、actualPrompt、model、provider、taskId、sourceResourceId、`assetKind`、`generationInputs`、创建时间和更新时间。上传素材被拖入画布时会复制为 project resource，图层只引用 resourceId；图片、图标和 UI 素材生成 BFF 在请求携带 `projectId` 时由后端直接创建新 resource，并把 `resourceId` 随生成响应返回给前端。图片生成请求如果同时携带 `canvasCompletion`（生成器 `dialogId`、标题和占位框），BFF 在生成成功后必须直接读取当前项目布局，只有当前布局仍存在对应 `generation-dialog` 时才插入轻量结果图层、把生成器标记为 `idle` 并写入 `generatedLayerId`，沿用后端当前 viewport 保存布局，再返回最新项目快照；前端只应用该快照刷新显示，不把生成完成态作为本地业务真相，也不在项目加载时根据资源行推断完成态。有项目上下文但后端没有返回项目快照时，前端不得本地补结果图层，只保留当前生成器交互状态等待下一次项目刷新。
+- 图片文件本体继续走 OSS，浏览器读取私有 generated 对象仍经 `/api/assets/read-url` 换签。
+- 当前 MVP 的本地上传先以 data URL 持久化在素材记录中，保证刷新和跨项目可见；后续接入正式 OSS 上传时，只替换 `imageSrc/objectKey/assetObjectId` 的写入方式，账号级素材表和画布资源表不变。上传到生成面板参考图槽位的图片必须先创建 `editor_project_resource` 行；没有当前工程 ID 时才创建账号级 `editor_asset` 行，随后把对应 `resourceId` 或 `assetId` 写入参考图临时状态，生成请求仍使用临时状态中的图片源或 `objectKey`。
+- 资源表保存资源和素材级元数据；图层位置、层级、分组选中所需 ID 和 groupId 保存在 `editor_canvas` 的布局 JSON。布局 JSON 是混合数组：普通图层按 `layerId/resourceId` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存，不新增单独表。普通图层的新保存不再把 `assetKind/generationInputs` 写入布局 JSON；刷新时优先从 `editor_project_resource` 恢复，旧布局中的同名字段只作为兼容兜底。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成器快照中的参考图同样只保存 `resourceId/sourceAssetId` 行引用和展示所需 label，不保存图片 Data URL、signed URL 或 `objectKey`；刷新时用 `editor_project_resource` / `editor_asset` 行恢复临时生成请求所需图片源。生成成功后仍保存该快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。`generationInputs.references` 是用户可见输入快照中的行级索引，只允许保存 `{ title, label, refType, refId }`；生成接口所需的图片 Data URL、signed URL 或 `objectKey` 只存在于提交前的临时参考图状态和请求体字段，不进入资源 / 素材元数据。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。
+- 图片类生成结果除作为 `editor_project_resource` 和画布图层保存外，还要写入账号级 `editor_asset` 素材库；该写入由生成 BFF 在请求携带 `assetFolderId` 时完成。带 `canvasCompletion` 的图片生成以 BFF 返回的 `project` 快照刷新画布；无项目上下文或没有返回快照时，前端才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。视频结果当前只保存为画布视频资源，不进入图片素材库。
+- 前端不直接订阅 SpacetimeDB，统一通过 api-server 的 `/api/editor/projects*` BFF 读写。
+- 未登录用户可以使用本地演示态，但不触发工程自动保存；真实图片生成 / 修改需要登录。编辑器 API 请求允许使用 refresh cookie 静默补 access token，但 401 / 403 只在编辑器局部提示登录，不清空整站登录态，也不把后端 requestId 直接作为生图弹窗主文案。
+
+## 后端接口
+
+- `GET /api/editor/projects/recent`：读取当前用户最近编辑的图片画布工程，没有则返回 `project: null`。
+- `GET /api/editor/projects`：读取当前用户所有图片画布工程，按更新时间倒序返回。
+- `POST /api/editor/projects`：创建图片画布工程。
+- `GET /api/editor/projects/{projectId}`：读取指定工程及资源列表。
+- `PATCH /api/editor/projects/{projectId}`：保存 viewport 与图层布局快照。
+- `PATCH /api/editor/projects/{projectId}/metadata`：重命名指定工程。
+- `DELETE /api/editor/projects/{projectId}`：删除指定工程，并级联删除默认画布和资源元数据。
+- `POST /api/editor/projects/{projectId}/resources`：创建画布资源记录，接收上传资源或真实生成资源元数据。
+- `GET /api/editor/assets/library`：读取当前账号的素材文件夹和素材。首次读取时自动创建“项目素材”默认文件夹。
+- `POST /api/editor/assets/folders`：新建素材文件夹。
+- `PATCH /api/editor/assets/folders/{folderId}`：重命名、折叠 / 展开素材文件夹。
+- `DELETE /api/editor/assets/folders/{folderId}`：删除素材文件夹；系统默认文件夹不能删除，普通文件夹删除时素材移入默认文件夹。
+- `POST /api/editor/assets`：批量或单个创建账号级素材，支持按钮上传和拖拽上传后的 data URL / 后续 OSS 元数据。
+- `PATCH /api/editor/assets/{assetId}`：重命名素材或移动素材到文件夹。
+- `DELETE /api/editor/assets/{assetId}`：删除素材。已放入画布的 project resource 不被级联删除，避免旧画布丢图。
+- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片；角色生成可携带 `model`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits。携带参考图的快速编辑也走该接口，前端必须把参考图源预读成图片 Data URL 后放入 `referenceImageSrcs`；请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成成功后创建 project resource / 账号素材并在响应中返回 resource / asset 快照。
+- `POST /api/editor/icon-spritesheets/generations`：按图标规范图和素材描述数组生成 spritesheet，再由后端切分为独立透明图标。请求支持 `model`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置的 `icon` 档位（首版 12 泥点），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。后端把 spritesheet 和拆分后的 icon 都保存为 project resource / 账号素材，并随响应返回对应快照。
+- `POST /api/editor/ui-designs/assets/extractions`：以 UI 设计图 Data URL 作为参考图，固定 `gpt-image-2` 和提示词 `提取画面中的所有独立并整理成spritesheet` 生成素材 spritesheet，再按连通域自动拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，后端保存 spritesheet / 拆分素材并返回对应 resource / asset 快照；前端必须把 spritesheet 原图与拆分素材都加入画布。
+- `POST /api/editor/images/edits`：按提示词和当前图片 Data URL 调用 VectorEngine edits，返回新的生成图片元数据；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。
+- `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音、默认联网搜索标记和泥点价格生成视频。前端可选模型为 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，默认 `seedance2.0-fast`；后端必须将 `seedance2.0-fast` 映射到 `doubao-seedance-2-0-fast-260128`，将 `seedance2.0` 映射到 `doubao-seedance-2-0-260128`，两者不得混用。后端允许 6 类比例、4 到 15 秒整数、`480p / 720p / 1080p`，并拒绝 `seedance2.0-fast + 1080p`；`sound=on/off` 映射 Ark `generate_audio=true/false`。后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS，返回 `videoSrc`、尺寸、prompt、model、provider、taskId、durationSeconds、resolution 和 `priceMudPoints`。
+
+所有写接口都必须校验 Bearer 登录态和 owner；接口只返回当前用户有权读取的工程与资源。
+
+## 实现约束
+
+- 前端只维护表现、交互和临时 UI 状态，工程真相以后端 project/resource 快照为准。
+- 示例素材可继续复用 `public/creation-type-references/` 下的站内图片；用户上传和后续生成资源必须通过资源记录表达。
+- 不把 hover、dragging、临时吸附线、Space 临时抓手等瞬时 UI 状态写入后端。
+- 不在 UI 中加入大段功能说明，编辑器界面只展示必要的工具、素材和状态信息。
+- 不复用或改写 `CreativeImageInputPanel` 的单图资产编辑语义；`/editor/canvas` 是独立图片画布工程的画布入口。
+
+## 验收用例
+
+- 缩放百分比按钮能打开 Lovart 风格菜单，菜单项能放大、缩小、显示所有元素和缩放到固定比例。
+- `显示画布所有元素` 按可见图层外接矩形计算 viewport。
+- 左下角小地图可展示当前图层分布和视口范围，开关按钮可隐藏 / 恢复小地图，背景色菜单可切换白色、浅灰、暖灰和冷蓝工作区底色。
+- 默认选择模式；底部工具栏能切换工具；中键拖拽和 Space 临时抓手都能平移画布。
+- 拖拽图片或生成占位框接近其它图片 / 生成占位框边缘、中心或等距分布位置时显示吸附线，并保存吸附后的最终布局。
+- 生成图片点击后显示画布内 `Image Generator` 占位框和跟随占位框的生成输入框，生成失败保留占位和输入状态，生成成功后在占位位置创建真实图层，并让输入框继续跟随该生成图。
+- 生成中的占位图聚焦后支持键盘 `Delete` / `Backspace` 删除，不新增可见删除按钮；删除后对应异步回写必须按生成器 ID 判空并丢弃，不能把已删除素材重新落回画布。音乐 / 音频生成占位和已生成音频图层同样必须支持键盘删除。
+- 生成器快照刷新后必须恢复；待生成、生成中、失败和已生成后跟随成品图层的生成器都不能因为刷新丢失输入、参数、参考图或占位框位置。宣发素材生成器刷新后必须继续显示正确的卡片类型、游戏名、分类、描述和已绑定参考图。
+- 画布多选语义必须同时覆盖普通图层和仍显示占位框的生成器对象：Shift 点选或框选可把生成器加入当前选择；拖动任一已选图层或生成器时，所有已选普通图层和生成器占位框同步移动；删除 / Backspace / Delete 作用于完整选择集合，移除所有已选图层和生成器对象。生成器对象在选择集合中使用稳定 `generation-dialog:<id>` 目标 ID，不把生成器伪装成普通图层，也不新增后端表。
+- 生成类入口打开画布内面板时，底部 AI 工具栏必须保持可见；`生成规范`、角色 / 图标规范来源、角色常规参考图来源这类轻量菜单通过页面级 fixed portal 渲染，不能留在底部工具栏或参考图横向滚动容器内部，避免被局部 `overflow` 裁切。角色规范和常规参考图来源菜单必须向上弹出；常规参考图点击后先选择“从画布中选择”或“上传图片”，从画布取图时只绑定参考图，不触发普通画布图层选中、聚焦、面板隐藏或拖拽逻辑，绑定后退出画布选择状态。所有生成面板参考图槽位统一为方形图标组件；角色规范槽位只显示规范 logo 和 `角色规范` 四字，绑定来源标题只保留给可访问名称、悬浮 title 和图片信息。已有参考图槽位只有在 hover / focus 时显示右上角 `×`，点击后只解绑对应参考图。
+- 生成规范类图片面板底部必须以禁用态参数按钮显示 `16:9·2K` 和 `gpt-image-2`，视觉对齐可编辑面板参数控件，提交到 `/api/editor/images/generations` 时也固定携带这些参数。
+- 快速编辑面板底部必须显示当前选择的比例 / 尺寸和模型，参数按钮可展开修改且视觉对齐其它可编辑面板；参考图请求顺序为额外参考图在前、原图作为隐式最后一张提交，信息面板输入快照只展示用户额外选择的参考图。
+- 点击生成、生成规范、生成角色形象或生成图标素材后创建的占位图可继续保留；点击画布空白区域让当前图片或占位图失焦时，关闭当前生成面板并移除图片选中样式，但不删除占位图本身。
+- 生成资源显示元数据按钮，元数据窗口展示来源、生成输入快照、model、task、Resolution 和 OSS 引用；生成输入快照只包含用户面板输入和参考图行引用，不包含后端拼接 Prompt，不再展示独立 Size 字段，也不渲染参考图 Data URL 缩略图。
+- 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景使用前端轻量去背并回写为新的工程资源快照；前端轻量去背必须复用共享 `chromaKey` 的绿幕 / 近白背景模型，不再只按四角颜色扩散，避免纯白角色主体或主体内部浅色区域被扣碎。UI设计图的提取素材固定走 `gpt-image-2` 和提示词 `提取画面中的所有独立并整理成spritesheet`，生成的 spritesheet 原图和拆分后的独立素材都作为画布图层保留。
+- 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。
+- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，前端先读取成 `data:image/*;base64,...` 再提交，后端不得再收到 `/creation-type-references/*`、`/generated-*` 或 OSS URL 作为 `referenceImageSrcs/sourceImageSrc`。
+- 快速编辑的额外参考图同样必须在前端读取成图片 Data URL 后提交；后端 `referenceImageSrcs` 上限为 9 张，承载 8 张额外参考图加 1 张原图。
+- 素材文件夹可以新建、折叠、重命名和删除；删除普通文件夹后，其素材移动到“项目素材”。
+- 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入默认素材文件夹并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入默认文件夹并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；仅在无法解析尺寸时才使用上传兜底尺寸。
+- 音频 / 视频素材卡和画布媒体图层必须提供稳定的非文字视觉预览：优先使用 `thumbnailSrc` / 视频 `poster`，没有真实首帧或音频封面时使用由媒体类型、素材名和地址派生的确定性视觉底图。视频图层使用原生 `<video controls preload="metadata" playsInline>` 播放，外层图层仍承接选择和拖拽语义；音频图层播放前继续通过 `/api/assets/read-url` 换签。画布素材导出按 `mediaType` 保留真实媒体格式：图片进入 `images/`，音频 / 视频进入 `media/`，文件扩展名从响应 MIME、`objectKey` 或源 URL 推断，不得把音频 / 视频导出成 PNG。
+- `生成角色动作` 的完成结果同样按视频素材处理：图层主 `src` 使用后端返回的 `previewVideoPath`，`mediaType` 固定为 `video`，`assetKind` 固定为 `character-animation`，首个透明帧只写入 `thumbnailSrc` 供 poster 和后续动作源使用。下载和 ZIP 导出必须因此得到 mp4/webm/mov 等真实视频文件，不能回退为首帧 PNG；后端抽帧、绿幕去背和帧素材落盘流程仍完整保留。
+- 素材面板支持选择模式框选，一次选中多个素材，并可批量移动或删除上传素材。
+- 图层面板支持选择多个图层后创建图层组，组名和 groupId 随画布布局保存。
+- 小地图支持拖拽视口框，拖动时画布 viewport 跟随移动。
+- 鼠标滚轮默认垂直滚动画布视口；按住 Ctrl / Cmd 滚轮才缩放画布，并阻止浏览器页面缩放。
+- 工程刷新后能从后端恢复资源、图层布局和 viewport。
+- “我的”页项目入口能进入 `/project`；项目页能列出工程、重命名 / 删除单个工程、批量选择和批量删除；点击工程后进入 `/editor/canvas?projectid=<projectId>` 并按 query 加载该工程。
+
+## 后续扩展点
+
+- 接入图片生成 / 修改计费、队列进度状态、OSS 落盘和更完整失败审计。
+- 资产库接入：素材栏从用户资产、历史生成图或上传结果读取。
+- 图层模型：引入稳定 layer id、z-index、锁定、隐藏和多选。
+- 图像编辑：继续扩展更精细的局部修改、蒙版、智能抠图与导出能力。
diff --git a/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md
new file mode 100644
index 000000000..16e136c58
--- /dev/null
+++ b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md
@@ -0,0 +1,251 @@
+# 图片画布编辑器前端拆分计划
+
+日期：2026-06-17
+
+## 背景
+
+`src/components/image-editor/ImageCanvasEditorView.tsx` 已承载图片画布的素材库、图层、生成对象、导出、右键菜单、拖拽、缩放、吸附、小地图和登录恢复等能力。文件体量超过八千行，阅读一个局部交互时需要先穿过大量无关类型、常量和纯函数，后续继续补齐 Lovart 式画布能力会持续放大维护成本。
+
+本轮拆分目标不是把界面拆成很多浅模块，而是先把稳定模型和纯逻辑放到有深度的模块中。主视图继续保留 React 状态编排和 JSX 工作面，避免第一轮把复杂交互拆成大量 props 透传。
+
+## 拆分原则
+
+- 类型、常量和纯函数优先拆出，React 状态闭环暂不拆散。
+- 模块接口要承载真实规则，不建立只转发一两个属性的浅模块。
+- 画布坐标、素材快照、生成输入快照和导出元数据分别放在相近规则的模块内，提升局部修改能力。
+- `ImageCanvasEditorView.tsx` 不再反向作为模型模块的依赖；依赖方向固定为 `View -> model/types/services`。
+- 任何拆分必须保持现有交互、持久化和测试断言不变。
+
+## 第一阶段模块
+
+- `ImageCanvasEditorTypes.ts`
+  - 承载编辑器前端共享类型：素材、图层、视口、工具、生成对象、历史快照、剪贴板、右键菜单、拖拽状态等。
+  - 只暴露类型，不承载运行时逻辑。
+
+- `ImageCanvasEditorModel.ts`
+  - 承载画布基础模型：尺寸、缩放、背景色、素材默认文件夹、快照序列化 / 水合、素材库快照映射、吸附、右键菜单定位、DataTransfer 工具和通用数值格式化。
+  - 保留“图片显示尺寸跟随 Resolution”“只保留一个默认素材文件夹”“右键菜单不滚动而是限制到视口内”等规则。
+
+- `ImageCanvasGenerationModel.ts`
+  - 承载生成相关模型：生成占位尺寸、默认模型、规范表单默认值、角色动画选项、生成输入快照、规范 prompt 构建、生成对象识别和错误文案。
+  - 保留角色动画优先用 `objectKey` 的体积保护规则。
+
+- `ImageCanvasExportModel.ts`
+  - 承载画布素材导出的底层规则：文件名清理、日期格式、图片去重 key、Data URL 转 Blob、Blob 读取和图层导出元数据。
+  - ZIP 组包和下载触发仍留在主视图，作为 UI 状态编排的一部分。
+
+## 第二阶段模块
+
+- `ImageCanvasSidebarView.tsx`
+  - 承载素材 / 图层共用左侧整合面板的 JSX，包括素材文件夹、新建 / 折叠 / 重命名 / 删除、上传入口、素材选择模式、框选层、批量删除、素材拖到文件夹和图层列表。
+  - 继续通过 props 调用主视图状态机，不接管上传、登录弹窗、持久化、拖到画布的坐标换算和图层历史记录。
+  - 保持“素材”和“图层”同一侧栏切换的 Lovart 式布局，不恢复右侧独立图层栏或左侧竖向工具栏。
+
+## 第三阶段模块
+
+- `ImageCanvasStageView.tsx`
+  - 承载中央画布工作区的视觉树：viewport / world DOM、图层渲染、生成占位框、选中图片浮动工具栏、空白和图片右键菜单、左下 dock、缩放菜单、背景设置面板、小地图和底部 AI 工具栏。
+  - 继续通过 props 调用主视图状态机，不接管拖拽 / 平移 / 缩放、画布坐标换算、历史 undo / redo、上传、登录、生成提交、素材持久化和右键命令实现。
+  - 保持 `canvasViewportRef` 由主视图传入，确保 pointer capture、drop 坐标、滚轮缩放和小地图拖拽仍使用同一套坐标源。
+  - 图片图层渲染必须和音频、视频一样走统一资源读取解析；图层存在 `objectKey` 时优先用它换签，避免重进项目后私有上传 / 生成资源只剩旧路径而无法显示。
+
+第三阶段以后，主视图仍是画布编排入口。继续拆分前应优先选择能形成稳定边界的深模块，避免把上传链路、DataTransfer、画布坐标和历史快照拆成互相回调的小碎片。
+
+## 第四阶段模块
+
+- `ImageCanvasGenerationComposerView.tsx`
+  - 承载生成图片、生成规范、生成角色形象、生成图标素材、快速编辑图片、角色动画和修改图片弹窗的视觉表单。
+  - 保留生成对象状态机、提交 API、上传文件 input、引用选择、生成结果回写、图层历史和坐标锚定在主视图内，避免把 Lovart 式生成对象拆成不可追踪的远程状态。
+  - 该组件可以管理局部字段输入和菜单展示，但所有会影响画布事实的动作都通过主视图回调落回原有状态机。
+
+## 第五阶段模块
+
+- `ImageCanvasLayerCommandModel.ts`
+  - 承载图层命令的纯数据规则：右键目标解析、复制快照、粘贴 / 创建副本定位、层级移动、分组 / 解组、显示 / 隐藏、锁定 / 解锁、水平 / 垂直翻转和删除。
+  - 主视图继续负责命令触发时机、历史快照、选中态、菜单关闭、元数据清理和导出下载等 UI / 浏览器副作用。
+  - 该模块有独立单测锁定当前右键菜单语义，避免后续调整 UI 时顺手改变图层数据规则。
+
+## 第六阶段模块
+
+- `ImageCanvasInteractionModel.ts`
+  - 承载画布交互纯计算：适合视图、中心缩放、普通滚轮纵向滚动、Ctrl / Cmd 滚轮缩放、画布坐标换算、框选命中、平移、生成占位框拖拽、图层拖拽吸附、小地图投影、小地图点击定位和小地图拖拽视图移动。
+  - 主视图继续负责 React 事件对象、pointer capture、history 快照、生成对象回写、选中态和 `setState`。
+  - 该模块用独立单测覆盖小地图灵敏度、吸附、多选拖拽和滚轮缩放等之前容易回退的交互规则。
+
+## 第七阶段模块
+
+- `useCanvasHistory.ts`
+  - 承载画布历史栈：快照创建、快照恢复、撤销、重做、历史栈长度限制和 `canUndo` / `canRedo` 派生状态。
+  - 主视图继续负责在具体用户动作前调用 `captureCanvasHistory`，并通过 hook 注入恢复快照后需要清理的 hover、元数据、框选、吸附、右键菜单和平移拖拽状态。
+  - 该 hook 有独立测试覆盖图层、视口、active / archived 生成对话框和选中态的撤销 / 重做恢复，避免后续把 history 逻辑继续埋回主视图。
+
+## 第八阶段模块
+
+- `useImageCanvasProjectPersistence.ts`
+  - 承载图片画布工程持久化协调：项目加载、`projectId` 维护、未就绪资源队列、工程资源创建、资源创建后即时 layout 保存、450ms 自动保存和鉴权失败登录弹窗。
+  - 该 hook 以“项目持久化协调器”整体抽出，避免把加载、保存和资源创建拆成多个小 hook 后打散 `projectIdRef`、`pendingProjectResourceLayersRef`、`isProjectReady` 和 `saveTimerRef` 的时序约束。
+  - 主视图继续负责项目重命名 UI、素材库管理、上传流程和用户动作触发；新增图层仍通过 `appendCanvasLayersWithResources` 先写本地图层快照，再创建 project resource 并保存带真实 `resourceId` 的 layout。
+  - 项目加载 hydrate 时必须从 project resource 回填 `objectKey`、`assetObjectId`、`sourceResourceId` 等资源元数据；layout 快照保持轻量，但重进项目后的画布图层仍要保留换签和后续编辑所需线索。
+
+## 第九阶段模块
+
+- `useCanvasGenerationDialogs.ts`
+  - 承载画布生成 dialog 注册表：active / inactive dialog 状态、id 分配、归档、激活、按 id 更新 / 删除、按关联图层清理，以及生成中异步回写时获取最新占位框。
+  - 该 hook 只处理 `generate/spec/character/icon` 这类画布生成对象，继续保留 `GenerateDialogState.mode === 'edit'` 的直接 `setGenerateDialog` 能力用于低风险迁移；真实生成请求、quick edit、角色动画、结果落图和资源持久化仍留在主视图。
+  - 主视图通过 `onActivate` 处理激活生成对象后的清空图层选择和关闭图片菜单等跨状态副作用，避免 dialog hook 反向依赖画布图层状态。
+
+## 第十阶段模块
+
+- `useImageCanvasAssetLibrary.ts`
+  - 承载账号级素材库状态模型：素材文件夹、素材列表、文件夹折叠 / 新建 / 重命名 / 删除、素材重命名 / 删除、素材选择模式、框选、多选删除、素材拖到文件夹和鉴权失败登录弹窗。
+  - 主视图继续保留上传文件读取、上传占位卡片进度、拖到画布坐标、创建画布图层、工程资源持久化和画布图层清理；素材删除通过 `onDeleteAssets` 回调通知主视图清理关联图层。
+  - 该 hook 有独立单测覆盖素材库加载归一化、401 登录、新建文件夹临时 id 替换、素材移动、删除回调和多选删除，避免后续整理侧栏 JSX 时丢失素材库能力。
+
+## 第十一阶段模块
+
+- `ImageCanvasFileModel.ts`
+  - 承载图片文件判定和 `FileReader` Data URL 读取工具，供素材上传、生成参考图上传和后续导入能力复用。
+  - 该模块不依赖素材库状态，避免把通用文件读取继续挂在素材库 hook 上。
+
+- `useImageCanvasUploadWorkflow.ts`
+  - 承载图片画布上传工作流：隐藏文件 input、上传目标分发、未登录拦截和登录后续传、上传占位卡片、文件读取、素材落库、拖到画布建层、选中新图层、打开图层侧栏，以及角色 / 图标生成参考图上传。
+  - 主视图继续负责画布 drop 外层事件判断、素材库已有素材加入画布、项目资源持久化 hook 注入和画布历史捕获，避免上传 hook 反向成为画布全局状态真相。
+  - 该 hook 用独立单测覆盖登录续传、上传占位 / 成功回写、上传到画布建层、鉴权失败和生成参考图分发，主视图保留 DOM 级 smoke 覆盖侧栏上传、画布 drop 上传和文件夹定向上传。
+  - 普通素材上传入口必须在打开系统文件选择器前检查登录态；未登录时先弹 `账号入口`，登录后由用户再次点击上传入口打开选择器，避免浏览器拦截异步触发的系统文件选择器。角色 / 图标生成参考图只作为本地引用进入生成表单，不强制登录。
+
+## 第十二阶段模块
+
+- `ImageCanvasGenerationLayerModel.ts`
+  - 承载生成结果落画布的纯数据规则：普通生图、修改图片、快速编辑和图标素材批量结果如何生成图层 id、临时 resourceId、标题、位置、原始分辨率尺寸、zIndex、source metadata、`assetKind`、源图关联和 `generationInputs`。
+  - 主视图继续负责生成提交 API、生成对象 active / archived 状态、资源持久化、图层选择、侧栏切换、对话框收起和适合视图等副作用，避免把多个画布生成对象的生命周期拆成浅 wrapper。
+  - 该模块用独立单测锁定“图片显示尺寸跟随原始 Resolution”“生成占位框只作为定位参考”“图标素材沿用当前行宽换行规则”和“快速编辑保留源图分组 / 类型”的规则。
+
+## 第十三阶段模块
+
+- `useImageCanvasAssetExportWorkflow.ts`
+  - 承载画布素材导出工作流：导出状态、空画布提示、单图右键导出、整包 ZIP 组包、图片去重、读取失败记录、`metadata.json`、`manifest.txt`、下载链接创建和浏览器不支持时的错误提示。
+  - 主视图继续负责右键菜单目标解析、下载按钮渲染和状态提示展示；导出 hook 不接管图层选择、右键菜单生命周期或画布状态。
+  - 该 hook 用独立单测覆盖 ZIP 内容、重复图层复用同一图片文件、失败图片 metadata、manifest 失败数量、空画布提示和单图文件名清理。
+
+## 第十四阶段模块
+
+- `useImageCanvasLayerCommands.ts`
+  - 承载图层命令工作流：画布剪贴板、右键目标解析、复制 / 剪切 / 粘贴、创建副本、层级移动、分组 / 解组、显示 / 隐藏、锁定 / 解锁、翻转、删除选中图层、按 id 删除图层和单图导出委托。
+  - 主视图继续负责右键菜单定位、画布事件、生成提交、素材上传、项目持久化和实际下载实现；hook 只接收必要 setter 与副作用回调，不反向读取 DOM 或路由。
+  - 该 hook 用独立单测覆盖菜单关闭、历史捕获、选中态更新、删除副作用、剪贴板和导出委托，避免主视图后续继续堆积右键菜单 orchestration。
+
+## 第十五阶段模块
+
+- `useImageCanvasGenerationWorkflow.ts`
+  - 承载图片画布生成工作流：打开普通生图 / 规范 / 角色 / 图标生成对象、打开修改图片 / 快速编辑 / 角色动画面板、选择画布规范参考、提交真实生成 API、失败恢复、生成结果落图、侧栏切换、适合视图和删除图层后的生成态清理。
+  - 主视图继续负责画布事件、生成对话框定位样式、占位框拖拽、DOM 渲染、上传入口、工程资源持久化和历史捕获；生成 hook 只接收状态 setter 与落图 / 选中 / 适合视图回调。
+  - 该 hook 用独立单测覆盖打开生成占位、普通生图落图、快速编辑落图并适配源图、删除源图时清理 quick edit / edit dialog、角色动画入口过滤和隐藏生成面板不删除占位框，避免后续拆分再次导致生成工具或底部工具栏状态回退。
+
+## 第十六阶段模块
+
+- `useImageCanvasEditorChrome.ts`
+  - 承载编辑器 chrome 状态：项目标题 / 重命名、左侧栏开关、当前工具、缩放菜单、背景设置面板、小地图开关、画布背景色和 HEX 输入。
+  - 主视图继续负责真正跨工作流的动作编排，例如上传工具触发上传工作流、生成工具触发生成工作流、项目加载后注入标题、键盘 Escape 同时关闭生成 / 快速编辑 / 图片菜单等非 chrome 面板。
+  - 该 hook 用独立单测覆盖项目重命名、鉴权失败登录、背景色合法 / 非法 HEX、侧栏切换、缩放 / 背景面板关闭、小地图和工具状态，避免后续改顶部栏或左下 dock 时把这些状态重新散回主视图。
+
+## 第十七阶段模块
+
+- `useImageCanvasViewportControls.ts`
+  - 承载画布视口控制：`viewport`、`canvasSize`、小地图投影、适合视图、中心缩放、普通滚轮纵向滚动、Ctrl / Cmd 滚轮缩放、屏幕点到画布 / 世界坐标换算和小地图点击 / 拖拽移动视图。
+  - 主视图继续负责图层拖拽、生成占位框拖拽、框选、多选、历史触发时机、上传 drop 分流和小地图 pointer down 事件；该 hook 只作为视口控制协调器，不接管画布完整 pointer 状态机。
+  - 该 hook 用独立单测覆盖尺寸同步、适合视图、中心缩放、坐标换算、滚轮语义和小地图移动，为后续抽 `useImageCanvasStageInteractions` 预留更清晰的视口接口。
+
+## 第十八阶段模块
+
+- `useImageCanvasStageInteractions.ts`
+  - 承载画布舞台 pointer 状态机：选择 / 框选、多选图层拖拽、生成占位框拖拽、抓手 / Space 临时抓手 / 中键平移、小地图 click / drag 分流和吸附线状态。
+  - 主视图继续保留原生文件 / 素材 drop、右键菜单定位、上传工作流、生成提交、项目持久化和工具栏动作分流；舞台 hook 只接收这些能力需要的回调，不反向读取路由、API 或素材库状态。
+  - 该 hook 用独立单测覆盖多选拖拽、框选、临时抓手、生成占位拖拽和小地图 click / drag 分流；主视图 DOM 测试继续覆盖真实组件路径和历史上容易回退的浏览器级交互。
+
+## 第十九阶段模块
+
+- `useImageCanvasCanvasDropWorkflow.ts`
+  - 承载画布区域 drag over / leave / drop 分流：识别素材库拖拽 MIME、本地文件拖拽、画布遮罩状态、默认文件夹选择、素材入画布和文件上传到画布参数组装。
+  - 主视图继续提供已有能力注入：账号级素材列表、默认素材文件夹、屏幕点转画布 drop 点、素材建层、文件上传、素材移动高亮清理；drop hook 不直接创建资源、不访问 API，也不读取项目持久化状态。
+  - 该 hook 用独立单测覆盖素材库图片拖入画布、文件拖入画布、无关拖拽不拦截和 drag leave 清理遮罩；主视图集成测试继续覆盖真实 DOM 中的“素材库拖到画布”和“文件拖到画布”路径。
+
+## 第二十阶段模块
+
+- `ImageCanvasMetadataModalView.tsx`
+  - 承载图片信息弹窗渲染：图片类型、生成输入字段、参考图、模型、分辨率、Provider、Task 和 Object 信息。
+  - 主视图只保留 `metadataLayer` 状态和打开 / 关闭动作；图片信息的视觉结构、fallback 文案和 `UnifiedModal` 接入不再散在主视图底部。
+  - 该组件用独立单测覆盖生成图 metadata、上传图 fallback、参考图渲染和关闭回调；主视图集成测试继续覆盖从画布图层点击右上角信息按钮打开弹窗。
+  - 本阶段同步把项目 / 素材初始加载挂到 `AuthGate` 的受保护数据可访问状态之后；未登录进入编辑器只拉起 `账号入口`，不再抢跑 `/api/editor/*` 造成素材或工程读取 401 噪声。
+  - `重置画布视图` 按钮必须显式调用 `onFitLayers()`，不能把 React click event 作为目标图层数组透传给适合视图逻辑。
+
+## 第二十一阶段模块
+
+- `useImageCanvasKeyboardShortcuts.ts`
+  - 承载图片画布全局键盘快捷键：Ctrl / Cmd + Z 撤销、Ctrl / Cmd + Shift + Z 重做、Shift 按下态、Backspace / Delete 删除选中图层、删除可编辑生成占位、Escape 关闭临时面板，以及 Space 临时抓手。
+  - 主视图继续保留各工作流状态和具体副作用，例如图层删除、生成对话框、规格菜单、快速编辑面板和 chrome 面板状态；快捷键 hook 只接收 ref、setter 与回调，不直接读写素材库、路由或 API。
+  - 该 hook 用独立单测覆盖输入框忽略快捷键、撤销重做、选中图层删除、生成占位删除、Escape 保留生成中面板、Space 临时抓手和 Shift 状态；主视图 DOM 测试继续覆盖真实编辑器里的 Backspace、Escape、Space 和 undo / redo 集成路径。
+
+## 第二十二阶段模块
+
+- `useImageCanvasAssetPointerDragBridge.ts`
+  - 承载素材库卡片 pointer 拖拽桥接：全局 `pointermove` / `pointerup` / `pointercancel` 监听、拖拽激活阈值、画布 drop 提示、文件夹移动高亮、拖到文件夹移动素材、拖到画布创建图层，以及拖拽结束后的点击抑制。
+  - 主视图继续保留素材库事实、画布建层、历史捕获、工程资源持久化和素材移动 API 编排；该 hook 只作为“侧栏素材拖拽到画布或文件夹”的事件桥，不直接读写路由、API 或图层持久化。
+  - 该 hook 用独立单测覆盖拖拽激活、文件夹 drop、画布 drop、非激活拖拽清理和 pointer cancel 完成路径；主视图 DOM 测试继续覆盖真实素材库拖到画布和拖到文件夹的集成链路。
+  - 本阶段同步恢复认证弹窗使用 portal 渲染，避免 `/editor/canvas` 这类全屏画布内容把 `账号入口` 遮住；同时把画布背景设置面板调整为独立白色浮层，包含当前色、色域、色相、自定义颜色、预设网格、HEX 输入和恢复默认。
+
+## 第二十三阶段模块
+
+- `ImageCanvasOverlayModel.ts`
+  - 承载画布浮层定位纯规则：生成输入框锚定、图标素材生成面板横向扩宽、选中图片工具栏边界限制、快速编辑面板定位和角色动画面板定位。
+  - 主视图继续负责生成对象、quick edit、角色动画、视口和图层状态编排，只把可纯函数验证的屏幕坐标计算移出，避免后续调整 Lovart 式浮层时继续在主视图里散落坐标公式。
+  - 该模块用独立单测覆盖生成结果优先锚定、生成中 / 手动关闭隐藏输入框、icon 描述项宽度、图片工具栏 clamp、quick edit 和角色动画面板边界，以及画布生成 dialog 模式识别。
+  - 本阶段主视图从 1182 行降至 1133 行；下一步若继续拆分，可在该模型基础上抽更大的 `useImageCanvasStageController`，承接舞台派生状态、右键菜单和工具切换胶水。
+
+## 第二十四阶段模块
+
+- `useImageCanvasAssetCanvasBridge.ts`
+  - 承载素材库与画布之间的桥接工作流：删除素材时清理关联画布图层、素材加入画布创建图层、素材 pointer 拖入画布 / 文件夹、画布区域 drag over / leave / drop 分流，以及拖拽文件上传到画布的参数组装。
+  - 主视图继续掌握素材库事实、上传文件读取、工程资源持久化、历史捕获触发时机和实际 API 副作用；该 hook 只负责把已有素材 / 文件 drop 转成画布动作，不反向读取路由、登录态或项目数据。
+  - 该 hook 用独立单测覆盖素材建层、pointer drop 入画布和删除素材清理关联图层 / 选中态；原有 pointer drag 和 canvas drop hook 单测继续保留，主视图 DOM 测试继续覆盖真实素材库拖入画布路径。
+  - 本阶段主视图从 1133 行降至 1086 行；下一步可继续抽顶栏视图或更高内聚的舞台控制层，但应优先选择能收敛真实状态规则的深边界。
+
+## 第二十五阶段模块
+
+- `ImageCanvasStageControllerModel.ts`
+  - 承载舞台派生状态和右键菜单模型：选中图层、选中浮动工具栏位置、图片菜单图层、右键菜单目标图层，以及显示 / 解锁菜单文案判断。
+  - 该模型复用既有图层命令模型与浮层定位模型，不重新实现右键目标和选中工具栏坐标规则；生成 Composer 锚点不属于舞台控制器，后续由生成表面编排统一负责。
+  - 新增单测覆盖选中工具栏位置、右键目标集合、显示 / 解锁判断和菜单位置限制。
+
+- `useImageCanvasStageController.ts`
+  - 承载舞台控制胶水：清空画布焦点、空白画布右键菜单和图层右键菜单处理。
+  - 主视图继续保留工具切换、上传 / 生成入口、图层命令、项目持久化和舞台 pointer 状态机，避免把跨工作流动作塞进单个 hook。
+  - 本阶段主视图从 1086 行降至 993 行；后续若继续拆分，应优先考虑顶栏 / 项目标题区域或把侧栏图层右键入口并入同一舞台菜单控制层。
+
+## 第二十六阶段模块
+
+- `ImageCanvasTopbarView.tsx`
+  - 承载编辑器顶部栏视觉结构：返回项目入口、项目标题展示、项目标题重命名表单、下载画布素材按钮和导出状态提示。
+  - 主视图继续保留项目标题 / 重命名状态所属的 chrome hook、项目持久化、导出工作流和实际导出副作用；顶栏只负责表单事件和显示，不接管业务状态。
+  - 新增组件单测覆盖返回入口、标题编辑入口、重命名提交 / 取消、导出按钮禁用 / 启用和导出状态提示。
+  - 本阶段主视图从 993 行降至 905 行；后续可继续评估隐藏上传 input / 侧栏拖拽预览这类根级浮层是否值得抽为编辑器 shell 视图。
+
+## 第二十七阶段模块
+
+- `useImageCanvasGenerationSurface.tsx`
+  - 承载 Lovart 式生成表面编排：组合 `useImageCanvasGenerationWorkflow`，统一计算普通生图、图标生成、快速编辑和角色动画的浮层位置，并构建 `ImageCanvasGenerationComposerView` 节点。
+  - `useImageCanvasGenerationWorkflow` 继续作为生成状态机和真实 API 提交入口；生成表面 hook 只收口 Composer JSX、工具切换分流和浮层定位，避免主视图继续维护大段生成 props 胶水。
+  - 本阶段同步把生成 Composer 锚点从 `ImageCanvasStageControllerModel` 移出，避免舞台控制器和生成表面各自计算一套生成浮层状态。
+  - 新增 hook 单测覆盖生成工具切换、Composer 位置、关闭生成输入框和规范菜单；主视图从 905 行降至 793 行。
+
+## 后续阶段
+
+- 后续可继续选择更高内聚的交互 workflow 或持久化边界，不再把生成链路继续拆成浅层 wrapper。
+- 工程资源持久化、工具切换和历史捕获仍在主视图编排，拆分前需要先确认不会破坏多生成对象同时存在、完成时读取最新占位框、素材拖拽上传位置和角色动画优先传 `objectKey` 的历史保护规则。
+
+## 验证计划
+
+- `npm run test -- src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/ImageCanvasStageControllerModel.test.ts src/components/image-editor/useImageCanvasStageController.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx`
+- `npm run typecheck`
+- `npm run check:encoding`
+- `git diff --check`
+- 浏览器回归 `/editor/canvas`：确认登录弹窗、素材上传、背景设置面板、底部工具栏、Space 临时抓手、撤销 / 重做和画布基础渲染仍正常。
diff --git a/docs/technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md b/docs/technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md
new file mode 100644
index 000000000..90311ef06
--- /dev/null
+++ b/docs/technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md
@@ -0,0 +1,241 @@
+# AI Web 工程 Runner 与预览隔离威胁模型
+
+更新时间：`2026-06-13`
+
+## 范围
+
+本文约束 `/editor/agent` 浏览器内 AI Web 工程编辑器的 MVP：固定 React / Vite / TypeScript 静态模板、虚拟文件系统、独立 runner 构建、独立 origin iframe 预览。
+
+不覆盖 HMR、终端 shell、后端服务、任意依赖安装、任意端口代理和正式作品发布。这些能力进入后续阶段前必须单独补威胁模型。
+
+## 信任边界
+
+```text
+用户浏览器主站 origin
+  | /editor/agent 编辑器壳
+api-server 控制面
+  | 最小任务能力
+web-project-runner 执行面
+  | immutable artifact
+preview gateway / 独立 preview origin
+```
+
+关键原则：
+
+- 主站不执行 AI 工程代码。
+- api-server 不执行 AI 工程代码。
+- runner 无平台密钥、无宿主源码挂载、无 Docker socket。
+- 预览域和主站不同 origin。
+- 预览页拿不到平台 cookie、access token、SpacetimeDB、OSS 写权限或 LLM provider 密钥。
+
+## 资产与威胁
+
+| 资产 | 主要威胁 | MVP 缓解 |
+| --- | --- | --- |
+| 主站 access token / cookie | 预览代码同源读取、XSS 窃取 | 独立 preview origin；iframe 不带主站 cookie；预览页不能访问主站 storage |
+| 用户 Web 工程源码 | 跨租户读取、snapshot 枚举 | project / owner 校验；snapshotId 不可枚举；preview token 绑定 owner / project / snapshot |
+| preview artifact | 路径穿越、MIME 错误、旧 token 访问 | preview gateway 校验 token；禁止 `..`；按白名单 MIME 服务；短期 token 可撤销 |
+| runner 临时工作区 | 逃逸到宿主源码、读取密钥 | 独立临时目录或容器；非 root；无宿主源码挂载；任务结束销毁 |
+| 依赖缓存 | 缓存污染、恶意 postinstall | MVP 固定依赖；禁用 scripts；缓存 key 包含模板、Node 版本和 lock digest |
+| api-server / SpacetimeDB | runner 横向访问内部服务 | runner 默认无内网访问；阻断 api-server 管理端口、SpacetimeDB 和生产数据库 |
+| OSS / artifact store | 越权读写、签名 URL 泄露 | runner 只拿短期只读资产签名或受控写 artifact 能力；日志脱敏 |
+| 构建日志 | 泄露环境变量、宿主路径、签名 URL | 日志限长、脱敏、错误摘要化；不回显平台密钥 |
+| 用户浏览器 | 弹窗逃逸、下载、剪贴板、摄像头、Service Worker 常驻 | iframe sandbox；CSP；禁用 Service Worker；不授权敏感能力 |
+
+## Runner 限制
+
+runner 必须 fail-closed。每个 job 至少限制：
+
+- CPU。
+- 内存。
+- 磁盘。
+- 进程数。
+- 打开文件数。
+- 任务时长。
+- 日志大小。
+- artifact 大小。
+- 单文件大小。
+
+执行环境要求：
+
+- 非 root 用户。
+- 只读基础镜像。
+- 无 Docker socket。
+- 无宿主源码目录挂载。
+- 无平台 `.env`。
+- 无平台 token。
+- 临时工作区任务结束销毁。
+
+构建超时或资源超限时直接 kill，job 进入 `failed` 或 `expired`，保留可展示错误摘要，不推进 active preview。
+
+## 网络限制
+
+MVP 构建期默认无外网。若模板构建确实需要网络，只允许：
+
+- 平台受控 npm registry mirror。
+- 平台资产只读签名域。
+
+必须阻断：
+
+- RFC1918 内网网段。
+- 云 metadata 地址。
+- api-server 管理端口。
+- SpacetimeDB。
+- 生产数据库。
+- Docker daemon。
+- 任意用户配置 registry。
+
+需要覆盖 DNS rebinding 和 HTTP redirect 到内网的情况；不能只按初始 URL 字符串判断。
+
+## 预览 token
+
+preview token 必须满足：
+
+- 绑定 `ownerUserId`。
+- 绑定 `projectId`。
+- 绑定 `snapshotId`。
+- 绑定 `artifactId`。
+- 短期有效。
+- 可撤销。
+- 不可枚举。
+- 不能跨租户复用。
+
+访问无权限 artifact 应返回 `403` 或不可区分的 `404`，不得泄露其它项目是否存在。
+
+## Preview Gateway
+
+gateway 只读服务 immutable artifact。
+
+必须校验：
+
+- token 有效且未撤销。
+- artifact 属于 token 绑定 snapshot。
+- 请求路径规范化后仍在 artifact 根目录。
+- `index.html` fallback 只在 SPA 路由范围内生效。
+- MIME 类型来自白名单映射，不信任上传文件名。
+
+必须测试：
+
+- path traversal。
+- 错误 MIME。
+- HTML 注入。
+- 缓存串租户。
+- 旧 token 访问。
+- artifact 删除后访问。
+- token 过期后访问。
+
+## 浏览器隔离
+
+iframe sandbox MVP 建议最小化：
+
+```text
+sandbox="allow-scripts"
+```
+
+如果后续需要表单或同源能力，必须单独评审。MVP 不允许：
+
+- `allow-same-origin`
+- `allow-top-navigation`
+- `allow-downloads`
+- `allow-popups`
+- `allow-modals`
+- 摄像头。
+- 麦克风。
+- 剪贴板。
+- 地理位置。
+
+CSP 默认收紧：
+
+```text
+default-src 'none';
+script-src 'self';
+style-src 'self' 'unsafe-inline';
+img-src 'self' data: blob: https://assets.genarrative.world;
+font-src 'self' data:;
+connect-src 'none';
+frame-ancestors https://www.genarrative.world;
+worker-src 'none';
+```
+
+MVP 禁用 Service Worker 和持久缓存，避免恶意预览代码在用户浏览器里长期驻留。
+
+## Patch 校验
+
+AI 只能提交结构化 patch：
+
+- create file
+- update file
+- delete file
+- rename file
+- package manifest request
+
+api-server 必须拒绝：
+
+- 绝对路径。
+- `..`。
+- 符号链接。
+- `.env`、`.npmrc`、`.git`、`.ssh` 等隐藏敏感文件。
+- 超深目录。
+- 超大文件。
+- 超大总 snapshot。
+- 二进制膨胀。
+- 大 Data URL。
+- 可执行权限。
+
+前端编辑器可以显示校验错误，但正式准入以 api-server 为准。
+
+## 依赖供应链
+
+MVP 固定模板依赖，不开放任意 npm。即便用户或 AI 修改 `package.json`，也必须拒绝或忽略：
+
+- `preinstall`。
+- `install`。
+- `postinstall`。
+- `prepare`。
+- `git:` 依赖。
+- `file:` 依赖。
+- `http:` / `https:` tarball 依赖。
+- 私有 registry。
+- lockfile 篡改。
+- native build。
+- 二进制下载型包。
+
+后续开放白名单依赖时，必须加入依赖 resolver、registry mirror、封禁列表、许可证 / 安全扫描和缓存污染防护。
+
+## 审计与熔断
+
+必须记录：
+
+- `ownerUserId`
+- `projectId`
+- `snapshotId`
+- `jobId`
+- `artifactId`
+- `templateKey`
+- 依赖 lock digest
+- 构建耗时
+- 资源用量
+- 失败原因摘要
+- runner id
+- preview token 签发和撤销事件
+
+必须提供运维开关：
+
+- kill job。
+- 禁用项目。
+- 禁用 owner。
+- 禁用模板。
+- 禁用依赖。
+- 清理 artifact。
+- 暂停 runner。
+- 全局关闭 `/editor/agent` preview build。
+
+## 发布门禁
+
+临时 preview artifact 不能直接升为线上作品。作品化发布必须：
+
+- 重新构建。
+- 重新校验 snapshot。
+- 重新签发发布 artifact。
+- 使用 immutable artifact。
+- 走平台作品身份、公开详情、统计和权限链路。
diff --git a/docs/technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md b/docs/technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md
new file mode 100644
index 000000000..9991218ad
--- /dev/null
+++ b/docs/technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md
@@ -0,0 +1,488 @@
+# Editor Agent Mock Agent P1 落地计划
+
+更新时间：`2026-06-15`
+
+## 背景
+
+`/editor/agent` 的长期目标是浏览器内 AI Web 工程编辑器：用户通过自然语言和代码编辑生成一个完整 Web 工程，并在独立沙箱中预览。当前基础方案已确定为“平台编辑器壳 + api-server 控制面 + 独立 runner + 独立 preview origin”的四层结构。
+
+P1 阶段先不接真实 AI Agent，不调用 LLM、不接 `platform-agent`、不做 Agent 记忆、工具调用或多轮规划。P1 使用确定性的 mock Agent 生成结构化 patch，把风险集中在真正需要先验证的工程链路：项目、快照、patch 校验、静态构建、artifact、preview gateway、iframe 预览和刷新恢复。
+
+## P1 目标
+
+P1 完成一个可端到端验收的最小纵切：
+
+```text
+/editor/agent 输入 mock 指令
+  -> api-server mock Agent 生成结构化 patch
+  -> patch 校验并保存新 snapshot
+  -> 创建 preview build
+  -> runner 静态构建固定模板
+  -> 产出 immutable artifact
+  -> preview gateway 签发独立预览 URL
+  -> 前端 iframe 切换预览
+```
+
+P1 结束时，真实 Agent 仍可后置；后续只替换“需求文本 -> 结构化 patch”的来源，不推翻快照、构建和预览主链路。
+
+## 非目标
+
+P1 明确不做：
+
+- 真实 LLM / Agent 调用。
+- LangChain-Rust / `platform-agent` 接入。
+- 任意 npm 依赖安装。
+- AI 自定义 `package.json` scripts。
+- HMR、长驻 dev server、WebSocket 代理。
+- 终端 shell、后端服务、任意端口代理。
+- Web project 作品化发布。
+- 完整 lease / controller / worker 持久任务队列。
+- 与主站同源预览。
+- 把 AI 生成工程写入当前仓库源码目录。
+
+## 阶段边界
+
+P1 使用 mock Agent，但后续链路必须按生产架构实现：
+
+| 能力 | P1 做法 | 后续替换点 |
+| --- | --- | --- |
+| 需求理解 | api-server 内确定性 mock 规则 | Phase 2/3 接真实 Agent |
+| patch 生成 | mock Agent 返回结构化 patch | 保留同一 patch DTO |
+| patch 校验 | api-server 真实校验 | 继续复用 |
+| 快照保存 | SpacetimeDB 真实持久化 | 可拆对象存储优化 |
+| 静态构建 | runner 真实构建固定模板 | 可换成持久队列领取 |
+| artifact | 本地 / 受控 artifact store | 可换 OSS 或专用 artifact store |
+| 预览 | 独立 origin / 独立端口 iframe | 生产接独立域名 |
+
+## 与原始设计一致性检查
+
+P1 与 2026-06-13 的技术方案、威胁模型和验收清单总体一致：mock Agent 只替换“需求文本 -> 结构化 patch”的来源，不改变“编辑器壳 -> api-server 控制面 -> runner 执行面 -> preview gateway”的信任边界。
+
+为避免实现时放宽安全边界，P1 额外明确以下硬约束：
+
+| 主题 | 原始设计要求 | P1 执行口径 |
+| --- | --- | --- |
+| Agent | AI 只能提交结构化 patch | mock Agent 也只能返回结构化 patch，并必须经过同一后端校验 |
+| api-server | 控制面不执行 AI 工程代码 | api-server 可以创建 job 和触发 runner，但不得直接执行 `npm` / `vite` / 用户工程代码 |
+| 允许命令 | 平台固定构建命令，禁止 AI 自定义脚本 | runner 只允许固定 argv 命令清单，不经 shell，不执行 `npm run`、`npx` 或用户传入命令 |
+| 依赖 | 固定模板依赖，不开放任意 npm | P1 默认离线使用 runner 管理的模板依赖缓存；如需 registry，只能访问平台受控 mirror |
+| 工作区 | 独立临时目录或容器，无宿主源码挂载 | 每个 job 使用 runner 创建的任务级临时目录；禁止挂载当前仓库源码、`.env`、Docker socket 和宿主 `node_modules` |
+| 网络 | 构建期默认无外网 | 默认 deny all；只允许受控 npm mirror 和只读资产签名域，必须阻断内网、metadata、api-server、SpacetimeDB、Docker daemon |
+| artifact | immutable artifact，不复用临时目录 | artifact root 由 runner 配置，不来自请求；preview 只服务 artifact，不服务工作区 |
+| 预览 | 独立 preview origin | 开发态也必须使用独立端口 / origin；不得把预览挂在主站同源路径下 |
+| 状态机 | 失败不覆盖上一版预览 | 只有当前 active snapshot 的 `succeeded` build 能推进 active preview |
+
+## 契约设计
+
+P1 新增 Web Project 契约，Rust `shared-contracts` 与前端 `packages/shared` 保持同名字段。
+
+核心 DTO：
+
+```text
+WebProject
+WebProjectSnapshot
+WebProjectFile
+WebProjectPatch
+WebProjectPatchOperation
+WebProjectPreviewBuild
+WebProjectPreviewBuildEvent
+MockAgentTurnRequest
+MockAgentTurnResponse
+```
+
+P1 字段建议：
+
+- `projectId`：不可枚举字符串 ID。
+- `ownerUserId`：项目归属用户。
+- `templateKey`：固定为 `react-vite-ts-static`。
+- `activeSnapshotId`：当前编辑快照。
+- `activePreviewBuildId`：当前成功预览构建。
+- `files`：P1 可先存为 `Vec<WebProjectFile>` / JSON；只允许小型文本源码。
+- `patchSummary`：mock Agent 或用户编辑摘要。
+- `buildStatus`：`queued | running | succeeded | failed | cancelled | expired | stale`。
+- `previewUrl`：由 api-server 返回给前端，不由前端拼接。
+
+路径和内容限制必须写入契约注释和后端校验：
+
+- 只允许相对路径。
+- 拒绝绝对路径和 `..`。
+- 拒绝 `.env`、`.npmrc`、`.git`、`.ssh`。
+- 拒绝符号链接语义。
+- 限制目录深度、单文件大小、snapshot 总大小。
+- P1 只允许文本源码和少量静态资源。
+- `package.json` 不是事实源；新增依赖和 scripts 在 P1 拒绝或忽略。
+
+## 后端存储
+
+P1 新增 SpacetimeDB 表：
+
+```text
+web_project
+web_project_snapshot
+web_project_preview_build
+```
+
+`web_project`：
+
+- `project_id`
+- `owner_user_id`
+- `title`
+- `template_key`
+- `active_snapshot_id`
+- `active_preview_build_id`
+- `created_at`
+- `updated_at`
+
+`web_project_snapshot`：
+
+- `snapshot_id`
+- `project_id`
+- `owner_user_id`
+- `parent_snapshot_id`
+- `template_key`
+- `files_json`
+- `patch_summary`
+- `created_by`
+- `created_at`
+
+`web_project_preview_build`：
+
+- `job_id`
+- `project_id`
+- `snapshot_id`
+- `owner_user_id`
+- `status`
+- `logs_json`
+- `artifact_id`
+- `preview_token_id`
+- `preview_url`
+- `error_summary`
+- `created_at`
+- `started_at`
+- `finished_at`
+- `updated_at`
+
+落点：
+
+- `server-rs/crates/spacetime-module/src/web_project.rs`
+- `server-rs/crates/spacetime-module/src/lib.rs`
+- `server-rs/crates/spacetime-module/src/migration.rs`
+- `server-rs/crates/spacetime-client/src/mapper/web_project.rs`
+- `server-rs/crates/spacetime-client/src/web_project.rs`
+
+如果已有表新增字段，字段必须放在结构体最后并设置明确默认值；修改字段名或字段类型前必须确认迁移计划。schema 修改后必须执行：
+
+```bash
+npm run spacetime:generate
+npm run check:spacetime-schema
+```
+
+## api-server 控制面
+
+新增模块：
+
+```text
+server-rs/crates/api-server/src/web_project.rs
+server-rs/crates/api-server/src/web_project_mock_agent.rs
+server-rs/crates/api-server/src/modules/web_project.rs
+```
+
+P1 API：
+
+```text
+POST   /api/creation/web-project/projects
+GET    /api/creation/web-project/projects/{projectId}
+GET    /api/creation/web-project/projects/{projectId}/snapshot
+PATCH  /api/creation/web-project/projects/{projectId}/files
+POST   /api/creation/web-project/projects/{projectId}/mock-agent-turns
+POST   /api/runtime/web-project/projects/{projectId}/preview-builds
+GET    /api/runtime/web-project/preview-builds/{jobId}
+GET    /api/runtime/web-project/preview-builds/{jobId}/events
+```
+
+控制面职责：
+
+- 鉴权并校验项目 owner。
+- 创建固定模板项目。
+- 读取 active snapshot。
+- 校验用户编辑和 mock patch。
+- 保存新 snapshot。
+- 创建 preview build。
+- 触发 P1 runner 构建。
+- 记录构建日志和状态。
+- 构建成功后签发 preview URL。
+- 构建失败时保留上一版 active preview。
+
+`/events` 复用 `src/services/sseStream.ts` 的事件口径。P1 可以先用 api-server 内存广播或短轮询兼容，但外部契约必须保持 SSE：
+
+```text
+queued
+running
+log
+succeeded
+failed
+cancelled
+expired
+stale
+```
+
+## Mock Agent 规则
+
+mock Agent 必须确定性、可测试、不可绕过 patch 校验。
+
+输入：
+
+```json
+{
+  "prompt": "做一个蓝色计数按钮页面",
+  "baseSnapshotId": "snapshot_xxx"
+}
+```
+
+输出：
+
+```json
+{
+  "snapshot": "...",
+  "patch": {
+    "operations": [
+      {
+        "type": "updateFile",
+        "path": "src/App.tsx",
+        "content": "..."
+      }
+    ]
+  },
+  "summary": "更新首页计数按钮示例"
+}
+```
+
+P1 至少支持以下 mock 指令族：
+
+- `计数` / `按钮`：生成带计数按钮的 React 页面。
+- `卡片` / `列表`：生成卡片列表页面。
+- `蓝色` / `绿色` / `粉色`：调整 CSS 主题色。
+- `破坏构建`：生成一个 TypeScript 编译错误，用于验收失败保留上一版预览。
+- 其它输入：只更新标题和说明文案，避免 mock 分支过多。
+
+mock Agent 输出仍必须经过统一 `validate_web_project_patch(...)`，不得直接写表。
+
+## Runner 与构建
+
+P1 runner 可以先采用“api-server 创建 job 后触发一次性 runner 进程”的方式，不做持久 worker 队列；但执行面必须独立于 api-server、主站源码目录和预览域。api-server 只传递 job 身份和最小任务能力，不得在自身进程内执行构建命令。
+
+建议新增：
+
+```text
+server-rs/crates/web-project-runner
+```
+
+P1 runner 输入：
+
+- `jobId`
+- `projectId`
+- `snapshotId`
+- snapshot files 包。
+- artifact root 配置键或受控 artifact 写入能力。
+
+请求体、snapshot 或 mock Agent 输出中不得携带 runner 命令、构建参数、工作区路径或 artifact 输出路径。
+
+P1 runner 步骤：
+
+1. 创建任务级临时目录。
+2. 用 runner 内置模板或 runner 管理的只读模板缓存写入固定 React / Vite / TypeScript 模板。
+3. 规范化 snapshot 文件路径，写入前确认最终路径仍在任务临时目录内。
+4. 忽略或重写用户 `package.json` 的危险字段。
+5. 使用环境变量白名单启动子进程，清空平台密钥、`.env`、token、代理和私有 registry 配置。
+6. 执行平台固定命令清单。
+7. 限制 CPU、内存、磁盘、进程数、打开文件数、构建时间、日志长度、单文件大小和 artifact 大小。
+8. 成功后把 `dist/` 复制到 immutable artifact 目录；artifact 目录由 runner 配置计算，不接受请求指定。
+9. 失败时返回错误摘要和日志片段，日志需脱敏并避免完整宿主路径。
+10. 清理临时目录。
+
+P1 允许的构建命令只能来自平台常量，使用 argv 方式执行，不经 shell、不拼接字符串、不执行用户传入命令：
+
+```text
+npm ci --ignore-scripts --offline --no-audit --fund=false
+npm exec --offline -- vite build
+```
+
+如果离线缓存不足，P1 只能改为访问平台受控 npm registry mirror，并由 runner 写入受控 `.npmrc`；用户 snapshot 中的 `.npmrc`、registry、proxy、`package-lock.json` 篡改和新增依赖必须拒绝或重写。禁止为了开发速度复用当前仓库的 `node_modules`、源码目录或本机全局 npm cache 作为 runner 工作区输入。
+
+P1 默认网络策略为 deny all。仅当使用平台受控 registry mirror 或资产只读签名域时开放精确白名单；必须阻断 RFC1918 内网、云 metadata 地址、api-server 管理端口、SpacetimeDB、生产数据库、Docker daemon，并覆盖 HTTP redirect 和 DNS rebinding 到内网的情况。
+
+## Preview Gateway
+
+P1 开发态 preview 可以使用独立端口：
+
+```text
+http://127.0.0.1:<previewPort>/p/<previewToken>/
+```
+
+生产形态继续对齐独立域名：
+
+```text
+https://sandbox.genarrative.world/p/<previewToken>/
+```
+
+gateway 必须：
+
+- 校验 token。
+- 绑定 owner / project / snapshot / artifact。
+- 禁止 path traversal。
+- MIME 类型按白名单输出。
+- `index.html` fallback 只在 artifact 根内生效。
+- token 过期或 artifact 删除后返回确定错误。
+- 输出 CSP，默认 `connect-src 'none'`，并禁用 Service Worker 和持久缓存。
+- 不向预览页注入平台 access token、用户 cookie、SpacetimeDB、OSS 写权限或 LLM provider 密钥。
+
+preview gateway 可以与 api-server 共享代码仓库或部署单元，但服务静态 artifact 的入口必须是独立 listener / 端口 / vhost / origin；不得把 preview artifact 挂到主站同源路径下。
+
+前端 iframe：
+
+```text
+sandbox="allow-scripts"
+```
+
+P1 不增加 `allow-same-origin`、`allow-downloads`、`allow-popups`、`allow-top-navigation`。
+
+## 前端落点
+
+新增：
+
+```text
+src/components/editor/agent/WebProjectAgentEditorPage.tsx
+src/components/editor/agent/WebProjectAgentEditorPage.test.tsx
+src/components/editor/agent/webProjectAgentViewModel.ts
+src/services/web-project/webProjectClient.ts
+src/services/web-project/webProjectSse.ts
+src/services/web-project/webProjectClient.test.ts
+```
+
+入口路由：
+
+```text
+/editor/agent
+```
+
+P1 桌面布局：
+
+- 左侧文件树。
+- 中间代码编辑区，P1 可先用 `<textarea>`。
+- 下方或右侧 mock Agent 输入区。
+- 构建日志区。
+- 右侧 iframe 预览。
+
+P1 移动端布局：
+
+- 使用 tabs：文件、代码、预览、日志。
+- 不默认展示大段功能说明文案。
+- 预览 iframe 保持可见尺寸和明确加载 / 失败状态。
+
+前端状态原则：
+
+- active preview 来自后端返回，不由前端自行推断。
+- 构建失败不清空已有 iframe。
+- 刷新后先读取项目和 active snapshot，再恢复未终态 job 订阅。
+- 用户连续编辑触发新 snapshot 时，旧 build 只能显示为旧日志，不得覆盖新 preview。
+
+## 任务拆分
+
+| 编号 | 任务 | 主要文件 | 完成标准 |
+| --- | --- | --- | --- |
+| P1-01 | 契约与 DTO | `shared-contracts`、`packages/shared` | 前后端类型通过，字段和状态枚举一致 |
+| P1-02 | SpacetimeDB 表与 procedure/facade | `spacetime-module`、`spacetime-client` | 能创建项目、保存 snapshot、记录 build |
+| P1-03 | api-server Web Project 模块 | `api-server/src/web_project.rs` | API 鉴权、owner 校验、读写 snapshot |
+| P1-04 | mock Agent | `api-server/src/web_project_mock_agent.rs` | 指令生成 patch 且走统一校验 |
+| P1-05 | P1 runner | `server-rs/crates/web-project-runner` | 固定模板可构建，失败有日志摘要 |
+| P1-06 | preview gateway | `api-server` 或独立 runner/gateway | 独立 URL 可服务 artifact，token 校验生效 |
+| P1-07 | `/editor/agent` 页面 | `src/components/editor/agent` | 端到端可创建、编辑、构建、预览 |
+| P1-08 | 自动化与 smoke | 测试文件、验收脚本 | happy path 和失败保留旧预览通过 |
+
+## 验收场景
+
+P1 必须通过：
+
+1. 打开 `/editor/agent`，创建固定模板项目。
+2. 输入“做一个蓝色计数按钮页面”。
+3. mock Agent 返回结构化 patch。
+4. api-server 保存新 snapshot。
+5. 前端创建 preview build。
+6. runner 构建成功并产出 immutable artifact。
+7. SSE 返回 `queued -> running -> succeeded`。
+8. iframe 切换到新 preview URL。
+9. 输入“破坏构建”。
+10. 新 build 进入 failed，页面展示错误摘要。
+11. 上一版 active preview 仍保留。
+12. 刷新 `/editor/agent` 后，项目、active snapshot、active preview 和未终态 job 状态可恢复。
+
+安全验收必须覆盖：
+
+- 绝对路径被拒绝。
+- `..` 被拒绝。
+- `.env` / `.npmrc` / `.git` / `.ssh` 被拒绝。
+- 修改 `package.json` 新增依赖被拒绝或忽略。
+- 用户传入构建命令、scripts、registry、proxy 被拒绝或忽略。
+- runner 构建命令不经 shell，且只来自平台 allowlist。
+- runner 无平台密钥环境变量、无宿主源码挂载、无 Docker socket、无宿主 `node_modules` 输入。
+- runner 只能在任务级临时目录写入 snapshot，路径解析后不能逃逸工作区。
+- 构建期默认无外网；允许网络时只能访问平台白名单域名。
+- artifact root 不来自请求，preview 不服务 runner 临时工作区。
+- preview iframe 与主站不同 origin。
+- preview gateway 输出 CSP，禁止 Service Worker 和未白名单 `connect-src`。
+- failed / cancelled / expired / stale 不覆盖 active preview。
+
+## 验证命令
+
+后端与 schema：
+
+```bash
+npm run spacetime:generate
+npm run check:spacetime-schema
+cargo test -p spacetime-module web_project --manifest-path server-rs/Cargo.toml
+cargo test -p spacetime-client web_project --manifest-path server-rs/Cargo.toml
+cargo test -p api-server web_project --manifest-path server-rs/Cargo.toml
+```
+
+前端：
+
+```bash
+npm run test -- src/services/web-project
+npm run test -- src/components/editor/agent
+npm run typecheck
+npm run check:encoding
+git diff --check
+```
+
+浏览器 smoke：
+
+```text
+打开 /editor/agent
+创建模板项目
+提交一次 mock Agent 指令
+等待静态构建成功
+确认 iframe 展示新预览
+提交一次破坏构建的 mock 指令
+确认错误出现且上一版预览仍保留
+刷新页面确认项目、日志和 active preview 可恢复
+```
+
+## 风险与处理
+
+- Runner 与 api-server 边界被做薄：P1 可以由 api-server 触发 runner，但 runner 仍必须独立工作区执行，不能在主站源码目录构建。
+- mock Agent 绕过校验：mock 输出必须走同一 patch DTO 和后端校验函数。
+- P1 为赶进度直接同源预览：禁止；开发态也要独立端口或独立 origin。
+- snapshot 存大 JSON 后续膨胀：P1 限制总大小；P2 再拆 digest/object store。
+- 失败覆盖成功预览：状态机必须以 active snapshot 和 succeeded build 双条件推进 active preview。
+
+## 后续衔接
+
+P1 完成后进入 P2 时，优先补：
+
+- `web_project_runtime_job` 持久任务表。
+- lease / controller / worker 模式。
+- 手动取消、stale、expired 和 runner crash 恢复。
+- 构建日志分页与可重连 SSE。
+- 真实 Agent 接入，但继续产出同一结构化 patch。
+
+真实 Agent 接入前不得扩大 P1 的执行权限；任意依赖安装、HMR、dev server 和作品化发布必须进入后续独立评审。
diff --git a/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md b/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md
new file mode 100644
index 000000000..694bdb77e
--- /dev/null
+++ b/docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md
@@ -0,0 +1,358 @@
+# 浏览器内 AI Web 工程沙箱预览方案
+
+更新时间：`2026-06-13`
+
+## 背景
+
+`/editor/agent` 需要承载一个类似 IDE 的 AI Web 工程编辑器：用户在浏览器里看到文件树、代码编辑、AI 指令输入、构建日志和实时预览，AI 生成的是一个完整 Web 工程。这个工程的构建、依赖安装和运行必须与 Genarrative 主站、当前仓库源码目录、平台密钥和正式业务数据隔离。
+
+第一版不追求“浏览器里完整云 IDE + 任意 npm + HMR + 后端服务”。目标是先跑通一个安全、可恢复、可验收的静态 SPA 预览闭环。
+
+## 结论
+
+MVP 采用四层结构：
+
+```text
+平台编辑器壳 /editor/agent
+  -> api-server 控制面
+  -> 独立 web-project-runner worker
+  -> 独立 preview origin / preview gateway
+```
+
+第一版只支持固定 React / Vite / TypeScript 静态模板、虚拟文件系统、结构化 AI patch、平台固定构建命令、独立 runner 静态构建和独立域 iframe 预览。
+
+MVP 明确不做：
+
+- 终端 shell。
+- 任意后端服务。
+- 任意端口代理。
+- HMR / 长驻 dev server。
+- 任意 npm 依赖安装。
+- AI 自定义 build shell script。
+- diff 视图。
+- 与主站同源的预览 iframe。
+- 将 AI 生成工程写入当前 Genarrative 仓库源码目录。
+
+## 分层职责
+
+### 平台编辑器壳
+
+入口路由固定为 `/editor/agent`。这一层只负责前端体验：
+
+- 左侧聊天、中间预览、右侧 IDE 的水平三分布局。
+- AI 指令输入、构建日志、当前项目版本和预览 iframe。
+- 右侧 IDE 默认只显示文件树；展开后显示当前文件内容，并隐藏左侧聊天栏。
+- 保存用户编辑和 AI patch。
+- 订阅构建 job SSE 状态。
+- 在构建成功后切换 iframe 的 `previewUrl`。
+- 构建失败时保留上一版可用预览。
+
+平台编辑器壳不得直接执行用户工程代码，不持有 runner 临时工作区路径，不把平台 access token、用户 cookie、SpacetimeDB 连接信息或 OSS 写权限暴露给预览页。
+
+如果后续接入现有创作链路，入口仍应走 `play_flow` 主干和 `shared-contracts` DTO，不在前端壳或 `app.rs` 中新建平行业务流程。
+
+### 智能体编排器
+
+`/editor/agent` 的智能体不是普通聊天页，也不是直接生成整包代码的黑盒。它是“工程改动编排器”，负责把用户意图转成可审计、可校验、可回滚的 Web 工程 patch。
+
+智能体职责：
+
+- 理解用户自然语言目标，并结合当前 snapshot、文件树、选中文件和最近构建结果形成任务上下文。
+- 输出结构化 patch plan，而不是直接写真实目录或执行 shell。
+- 将 patch plan 提交给 api-server 校验，校验通过后生成新 snapshot。
+- 创建 preview build job，并订阅 job SSE。
+- 读取构建日志、错误摘要和 preview 状态，失败时继续生成修复 patch，成功时推动预览切换。
+- 保留每轮 agent turn 的用户输入、上下文摘要、patch 摘要、校验结果、jobId 和最终状态，便于刷新恢复和审计。
+
+智能体最小闭环：
+
+```text
+用户在左侧聊天输入需求
+  -> 前端提交 agent turn
+  -> api-server 读取当前 snapshot 和允许暴露的上下文
+  -> LLM 返回结构化 patch plan
+  -> api-server 校验 patch plan
+  -> 校验通过后生成新 snapshot
+  -> 创建 preview build job
+  -> runner 构建
+  -> SSE 回传 queued / running / log / succeeded / failed
+  -> 成功时中间预览 iframe reload
+  -> 失败时智能体基于错误摘要进入下一轮修复
+```
+
+智能体输出只允许以下 patch 操作：
+
+- `create_file`
+- `update_file`
+- `delete_file`
+- `rename_file`
+- `package_manifest_request`
+
+`package_manifest_request` 只是依赖请求，不是事实源。MVP 中 api-server 必须拒绝或忽略任意新增依赖、生命周期脚本、私有 registry、`git:` / `file:` / `http:` 依赖和 AI 自定义构建命令。
+
+智能体不得：
+
+- 直接写入当前 Genarrative 仓库源码目录。
+- 直接访问 runner 临时工作区。
+- 直接执行 shell、npm script 或任意构建命令。
+- 直接拿平台 access token、用户 cookie、SpacetimeDB 连接、OSS 写权限或 LLM provider 密钥。
+- 绕过 api-server 的路径、依赖、大小、敏感文件和 snapshot 校验。
+
+### 页面布局
+
+`/editor/agent` MVP 使用水平三分布局，不做 diff 视图：
+
+```text
+┌───────────────┬──────────────────────────────┬────────────────┐
+│ 左侧聊天      │ 中间预览                     │ 右侧 IDE       │
+│ Agent 对话    │ sandbox iframe + 状态日志    │ 默认文件树     │
+└───────────────┴──────────────────────────────┴────────────────┘
+```
+
+布局规则：
+
+- 左侧聊天承载用户输入、智能体回复、构建状态摘要和失败修复建议。
+- 中间预览始终是主工作区，展示当前 active preview iframe；构建失败时保留上一版 succeeded preview，并在聊天或日志区域展示失败摘要。
+- 右侧 IDE 默认只显示文件树，突出当前工程结构，不默认展示代码内容。
+- 用户展开右侧 IDE 后，右侧显示文件树和当前文件内容，左侧聊天栏隐藏，中间预览与右侧 IDE 形成双栏工作模式。
+- 用户收起右侧文件内容后，恢复左侧聊天 + 中间预览 + 右侧文件树三栏。
+- 文件内容查看用于理解和轻量编辑当前文件，不提供 diff 视图；版本变化通过 agent turn 摘要、snapshot 时间线和构建状态表达。
+- 移动端优先保持预览和聊天可用，右侧 IDE 通过抽屉或分段入口进入；展开文件内容时同样隐藏聊天。
+
+### api-server 控制面
+
+控制面只管理权限、快照、任务和状态，不执行 AI 工程代码：
+
+- 鉴权和项目归属校验。
+- 校验 AI patch 和用户编辑。
+- 保存虚拟文件系统 snapshot。
+- 创建 preview build job。
+- 给 runner 发放最小任务能力。
+- 输出构建日志和状态 SSE。
+- 签发短期 preview URL。
+- 将业务状态通过受控 procedure 或 BFF 更新到正式数据层。
+
+api-server 不把 SpacetimeDB、OSS 写权限、LLM provider、支付、用户 cookie 或平台内部 token 传给 runner。runner 需要读取资产时，只拿只读短期签名 URL 或受控 fixture。
+
+### web-project-runner worker
+
+新增独立进程角色，例如 `web-project-runner`。它可以复用外部生成 worker 的“任务表 + lease + controller + worker”模式，但不应把 Web 工程执行塞进 `external_generation_job`，避免语义污染。更合适的落点是新增 `web_project_runtime_job` 或抽象出通用 job 模块。
+
+runner 只做执行面：
+
+- 拉取指定 snapshot。
+- 展开到独立临时工作区或容器。
+- 使用平台白名单模板依赖。
+- 执行平台固定构建命令。
+- 采集构建日志、资源用量和结果。
+- 上传静态 artifact。
+
+runner 不能反向写平台业务表。业务状态回写必须经过 api-server / SpacetimeDB 的受控入口。
+
+### preview gateway 与独立预览域
+
+预览页使用独立 origin，例如：
+
+```text
+https://preview-<token>.sandbox.genarrative.world
+```
+
+或者统一域名加不可枚举 token path：
+
+```text
+https://sandbox.genarrative.world/p/<previewToken>/
+```
+
+预览域不得与主站同源，不带平台 cookie，不共享主站 `localStorage` / `sessionStorage`。主站只通过 sandbox iframe 嵌入预览。
+
+MVP 只服务静态构建产物。HMR、WebSocket 代理和长驻 dev server 后置到单独阶段评审。
+
+## MVP 流程
+
+```text
+用户在 /editor/agent 输入需求或编辑文件
+  -> AI 返回结构化 patch
+  -> api-server 校验 patch
+  -> 生成 workspace snapshot
+  -> 前端 debounce 后创建 preview build job
+  -> runner claim job 并构建静态 dist
+  -> artifact 上传 artifact store
+  -> preview gateway 只读服务 artifact
+  -> 前端 SSE 收到 succeeded 后 iframe reload
+```
+
+失败链路：
+
+```text
+构建失败 / 超时 / runner 崩溃
+  -> job failed / expired
+  -> 前端展示错误日志摘要
+  -> active preview 保持上一版 succeeded artifact
+```
+
+## 接口草案
+
+接口归属分成项目控制面和运行时控制面。
+
+```text
+POST   /api/creation/web-project/projects
+GET    /api/creation/web-project/projects/{projectId}/snapshot
+PATCH  /api/creation/web-project/projects/{projectId}/files
+POST   /api/creation/web-project/projects/{projectId}/agent-turns
+POST   /api/runtime/web-project/projects/{projectId}/preview-builds
+GET    /api/runtime/web-project/preview-builds/{jobId}
+GET    /api/runtime/web-project/preview-builds/{jobId}/events
+```
+
+`/events` 复用现有 `src/services/sseStream.ts` 的 SSE 传输层口径。事件类型建议包括：
+
+- `queued`
+- `running`
+- `log`
+- `succeeded`
+- `failed`
+- `cancelled`
+- `expired`
+- `stale`
+
+前端刷新恢复时，先读取项目 active snapshot 和 active preview，再按未终态 job 继续订阅 SSE。
+
+`agent-turns` 的请求建议包含：
+
+- `projectId`
+- `baseSnapshotId`
+- `message`
+- `selectedFilePath`
+- `visibleFilePaths`
+- `recentBuildJobId`
+
+`agent-turns` 的响应建议包含：
+
+- `turnId`
+- `status`
+- `assistantMessage`
+- `patchSummary`
+- `validationErrors[]`
+- `snapshotId`
+- `buildJobId`
+
+当 patch 校验失败时，不生成 snapshot，不创建 build job，只返回可展示的校验错误和智能体修正建议。
+
+## 虚拟文件系统
+
+平台内的“文件系统”是虚拟工作区，不是真实目录长期挂载。
+
+snapshot manifest 建议包含：
+
+- `projectId`
+- `snapshotId`
+- `parentSnapshotId`
+- `ownerUserId`
+- `templateKey`
+- `files[]`
+- `createdAt`
+- `createdBy`
+- `patchSummary`
+
+文件项建议包含：
+
+- `path`
+- `contentDigest`
+- `sizeBytes`
+- `mediaType`
+- `encoding`
+- `executable=false`
+
+路径必须 fail-closed：
+
+- 只允许相对路径。
+- 拒绝绝对路径。
+- 拒绝 `..`。
+- 拒绝符号链接。
+- 拒绝超深目录。
+- 拒绝超大文件。
+- 拒绝隐藏敏感文件名，例如 `.env`、`.npmrc`、`.ssh`、`.git`。
+- MVP 只支持文本源码和少量静态资源。
+
+文件内容小文本可以按 digest 存对象；大一点的 snapshot 可打包成 tar / zip artifact 放受控 artifact store。图片、音频等大资产继续走现有资产链路，不让 AI 工程随意内嵌大 Data URL。
+
+## 依赖和构建
+
+MVP 只支持平台预置模板依赖：
+
+- React
+- Vite
+- TypeScript
+- 平台已审核的 UI / 工具依赖子集
+
+`package.json` 在 MVP 中不是事实源。AI 可以提出 manifest patch，但 api-server 会重写或忽略危险字段。构建命令由平台固定，例如：
+
+```text
+npm ci --ignore-scripts
+npm exec vite build
+```
+
+第一版应禁止：
+
+- `preinstall` / `install` / `postinstall`
+- `git:` / `file:` / `http:` 依赖。
+- 私有 registry。
+- native build。
+- 二进制下载型包。
+- AI 自定义 shell script。
+
+后续若要开放依赖，必须进入“受控依赖白名单”和“隔离依赖解析服务”阶段，不混入 MVP。
+
+## 预览状态机
+
+```text
+draft snapshot
+  -> build queued
+  -> build running
+  -> build succeeded
+  -> build failed
+  -> build cancelled
+  -> build expired
+  -> build stale
+```
+
+状态规则：
+
+- 新 snapshot 触发新 build 时，旧 running build 应取消或标记 stale。
+- 只有当前 active snapshot 的 `succeeded` job 可以成为 active preview。
+- failed / cancelled / expired / stale 不能覆盖 active preview。
+- 回滚是切回历史 snapshot 并复用对应 immutable artifact，或重新构建该 snapshot。
+- 不允许复用 runner 临时目录作为回滚来源。
+
+## 后续阶段
+
+### Phase 0：文档和威胁模型
+
+补齐技术方案、威胁模型和验收清单，明确 MVP 不可做能力、安全门禁、状态机和 QA 口径。
+
+### Phase 1：静态模板预览纵切
+
+完成 `/editor/agent` 编辑器壳、固定模板、虚拟文件系统、AI patch 保存、runner 静态构建、artifact 服务和 iframe reload。
+
+### Phase 2：持久任务和恢复
+
+引入 `web_project_runtime_job`，按 lease / controller / worker 模式实现任务队列、取消、stale、刷新恢复和日志 SSE。
+
+### Phase 3：受控依赖安装
+
+支持白名单依赖、lockfile 固化、依赖层缓存、安装失败可读错误、依赖封禁和审计。
+
+### Phase 4：实时体验增强
+
+在安全评审后再做长驻 dev server、HMR、WebSocket 代理、端口租约和空闲回收。
+
+### Phase 5：作品化发布
+
+将通过安全门禁的 Web project 接入平台作品类型。发布必须重新构建 immutable artifact，不直接提升临时预览 artifact。
+
+## 与现有系统的关系
+
+- 前端 SSE 读取复用 `src/services/sseStream.ts`。
+- 后端 job 模式参考外部生成 worker 的 lease / controller 经验，但使用新的 Web 工程 runtime 语义。
+- `/editor/agent` 是第一版用户入口，不新增重复 IDE 页面。
+- 业务真相仍通过 server-rs + SpacetimeDB 受控写入，前端和 runner 都不能绕过控制面。
diff --git a/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md
new file mode 100644
index 000000000..45445ff21
--- /dev/null
+++ b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md
@@ -0,0 +1,226 @@
+# AI Web 工程静态预览 MVP 验收清单
+
+更新时间：`2026-06-13`
+
+## 范围
+
+本清单用于验收 `/editor/agent` 浏览器内 AI Web 工程编辑器 MVP。
+
+MVP 必须只支持：
+
+- 固定 React / Vite / TypeScript 静态模板。
+- 虚拟文件系统。
+- 结构化 AI patch。
+- 独立 runner 静态构建。
+- 独立 preview origin iframe 预览。
+- 失败保留上一版可用预览。
+- 左侧聊天、中间预览、右侧 IDE 的 `/editor/agent` 三分布局；右侧 IDE 展开文件内容后隐藏左侧聊天。
+
+MVP 不支持：
+
+- 终端 shell。
+- 后端服务。
+- HMR。
+- 任意端口代理。
+- 任意 npm 安装。
+- AI 自定义 package scripts。
+- diff 视图。
+- Service Worker。
+- 主站同源预览。
+
+## Happy Path
+
+- [ ] 用户打开 `/editor/agent` 能看到左侧聊天、中间预览和右侧 IDE 文件树。
+- [ ] 右侧 IDE 默认只显示文件树，不默认显示文件内容。
+- [ ] 用户展开右侧 IDE 后能看到当前文件内容，左侧聊天栏隐藏。
+- [ ] 用户收起右侧文件内容后恢复左侧聊天、中间预览和右侧文件树三栏。
+- [ ] 页面不展示 diff 视图。
+- [ ] 创建新 Web project 后得到固定模板文件树。
+- [ ] 用户在左侧聊天提交需求后创建 agent turn。
+- [ ] 智能体结合当前 snapshot、选中文件和最近构建状态生成结构化 patch plan。
+- [ ] AI patch plan 新增或修改一个 React 组件后，api-server 校验通过并生成新 snapshot。
+- [ ] patch 校验失败时不生成 snapshot，不创建 build job，并在聊天中展示可读校验错误。
+- [ ] 前端 debounce 后创建 preview build job。
+- [ ] runner 构建成功并产出 immutable artifact。
+- [ ] SSE 返回 `queued -> running -> succeeded`。
+- [ ] iframe 切换到新 preview URL。
+- [ ] 刷新 `/editor/agent` 后能恢复当前 project、active snapshot、active preview、agent turn 历史和未完成 job 状态。
+
+## 智能体编排
+
+- [ ] 智能体只通过 `agent-turns` 或等价受控接口提交用户需求，不直接写真实目录。
+- [ ] 智能体输出只包含 `create_file/update_file/delete_file/rename_file/package_manifest_request` 这类结构化 patch 操作。
+- [ ] 智能体不输出或执行 shell 命令。
+- [ ] 智能体不直接触发任意 npm script。
+- [ ] 智能体不直接访问 runner 临时工作区。
+- [ ] 智能体不接收平台 access token、用户 cookie、SpacetimeDB 连接、OSS 写权限或 LLM provider 密钥。
+- [ ] 每轮 agent turn 记录用户输入、上下文摘要、patch 摘要、校验结果、snapshotId、jobId 和最终状态。
+- [ ] 构建失败后，智能体基于受脱敏的错误摘要生成下一轮修复 patch。
+- [ ] 构建成功后，智能体不会覆盖非当前 active snapshot 的 preview。
+
+## Patch 与路径校验
+
+- [ ] 相对路径普通源码修改通过。
+- [ ] 绝对路径被拒绝。
+- [ ] `..` 路径被拒绝。
+- [ ] 符号链接被拒绝。
+- [ ] `.env` 被拒绝。
+- [ ] `.npmrc` 被拒绝。
+- [ ] `.git/` 被拒绝。
+- [ ] `.ssh/` 被拒绝。
+- [ ] 超深目录被拒绝。
+- [ ] 超大单文件被拒绝。
+- [ ] 超大 snapshot 被拒绝。
+- [ ] 大 Data URL 被拒绝或转资产流程。
+- [ ] 二进制膨胀被拒绝。
+- [ ] rename 后目标路径仍需重新校验。
+
+## 构建与状态机
+
+- [ ] job 状态覆盖 `queued/running/succeeded/failed/cancelled/expired/stale`。
+- [ ] 新 snapshot 创建后，旧 running job 被取消或标记 stale。
+- [ ] 只有当前 active snapshot 的 `succeeded` job 能推进 active preview。
+- [ ] failed job 不覆盖上一版 active preview。
+- [ ] cancelled job 不覆盖上一版 active preview。
+- [ ] expired job 不覆盖上一版 active preview。
+- [ ] stale job 不覆盖上一版 active preview。
+- [ ] 构建失败时展示可读错误摘要和日志片段。
+- [ ] 构建超时后 runner 被 kill，job 进入 failed 或 expired。
+- [ ] runner 崩溃后 job 能恢复为可重领或 expired。
+- [ ] 页面刷新后能通过 projectId / jobId 恢复日志和状态。
+- [ ] snapshot 回滚会复用对应 immutable artifact 或重新构建，不复用临时目录。
+
+## Runner 隔离
+
+- [ ] runner 进程无平台密钥环境变量。
+- [ ] runner 无宿主源码目录挂载。
+- [ ] runner 无 Docker socket。
+- [ ] runner 使用非 root 用户。
+- [ ] runner 工作区为任务级临时目录。
+- [ ] 任务结束后临时目录被销毁。
+- [ ] CPU 限制生效。
+- [ ] 内存限制生效。
+- [ ] 磁盘限制生效。
+- [ ] 进程数限制生效。
+- [ ] 打开文件数限制生效。
+- [ ] 日志大小限制生效。
+- [ ] artifact 大小限制生效。
+- [ ] 任务超时限制生效。
+
+## 网络隔离
+
+- [ ] 构建期默认不能访问公网。
+- [ ] 若允许 registry mirror，只能访问白名单域名。
+- [ ] 不能访问 RFC1918 内网地址。
+- [ ] 不能访问云 metadata 地址。
+- [ ] 不能访问 api-server 管理端口。
+- [ ] 不能访问 SpacetimeDB。
+- [ ] 不能访问生产数据库。
+- [ ] HTTP redirect 到内网时被阻断。
+- [ ] DNS rebinding 到内网时被阻断。
+
+## 依赖供应链
+
+- [ ] AI 修改 `package.json` 新增普通依赖时，MVP 拒绝或忽略。
+- [ ] `preinstall` 被拒绝或忽略。
+- [ ] `install` 被拒绝或忽略。
+- [ ] `postinstall` 被拒绝或忽略。
+- [ ] `prepare` 被拒绝或忽略。
+- [ ] `git:` 依赖被拒绝。
+- [ ] `file:` 依赖被拒绝。
+- [ ] `http:` / `https:` tarball 依赖被拒绝。
+- [ ] 私有 registry 被拒绝。
+- [ ] lockfile 篡改被拒绝或重写。
+- [ ] 构建命令由平台固定，不执行 AI 写入的 shell script。
+
+## Preview Token 与 Gateway
+
+- [ ] preview token 绑定 owner。
+- [ ] preview token 绑定 project。
+- [ ] preview token 绑定 snapshot。
+- [ ] preview token 绑定 artifact。
+- [ ] preview token 短期有效。
+- [ ] preview token 可撤销。
+- [ ] preview token 不可枚举。
+- [ ] 跨租户访问返回 403 或 404。
+- [ ] path traversal 被拒绝。
+- [ ] 错误 MIME 不会按可执行脚本服务。
+- [ ] SPA fallback 只在 artifact 根内生效。
+- [ ] artifact 删除后旧 URL 不能继续读取。
+- [ ] token 过期后旧 URL 不能继续读取。
+- [ ] preview cache 不串租户。
+
+## 浏览器隔离
+
+- [ ] 预览 origin 与主站 origin 不同。
+- [ ] 预览 iframe 不带主站 cookie。
+- [ ] 预览代码不能读取主站 `localStorage`。
+- [ ] 预览代码不能读取主站 `sessionStorage`。
+- [ ] 预览代码不能调用主站认证 API。
+- [ ] iframe sandbox 不允许 top navigation。
+- [ ] iframe sandbox 不允许 downloads。
+- [ ] iframe sandbox 不允许 popups。
+- [ ] iframe sandbox 不允许 clipboard。
+- [ ] iframe sandbox 不允许 camera / mic。
+- [ ] CSP 禁止未白名单 `connect-src`。
+- [ ] Service Worker 被禁用。
+
+## 日志与错误
+
+- [ ] 构建日志按 jobId 分段展示。
+- [ ] 日志限长。
+- [ ] 错误摘要可读。
+- [ ] 日志不包含平台 token。
+- [ ] 日志不包含 OSS 写签名。
+- [ ] 日志不包含完整宿主路径。
+- [ ] 日志不包含环境变量 dump。
+- [ ] SSE 断开后前端可重新拉取 job 状态。
+
+## 取消、回滚与并发
+
+- [ ] 用户连续编辑触发多个 snapshot 时，只保留最新 snapshot 的 active build 候选。
+- [ ] 用户手动取消当前 build 后，runner 停止或 job 被标记 cancelled。
+- [ ] 两个标签页同时编辑同一项目时，有明确版本冲突或 last-write 策略提示。
+- [ ] 回滚到历史 snapshot 后，active preview 对应历史 snapshot。
+- [ ] 历史 artifact 缺失时可重新构建。
+- [ ] 构建队列积压时 `/editor/agent` 显示确定状态，不假装实时完成。
+
+## Artifact GC
+
+- [ ] 未引用的 failed artifact 会清理。
+- [ ] 过期 preview artifact 会清理。
+- [ ] active preview artifact 不会被误删。
+- [ ] 历史 snapshot 的可回滚 artifact 按保留策略保留或可重建。
+- [ ] GC 后 preview gateway 对已删除 artifact 返回确定错误。
+
+## 最小自动化验证建议
+
+后端 / runner：
+
+```bash
+cargo test -p api-server web_project --manifest-path server-rs/Cargo.toml
+cargo test -p spacetime-module web_project --manifest-path server-rs/Cargo.toml
+```
+
+前端：
+
+```bash
+npm run test -- src/services/sseStream.test.ts
+npm run test -- src/components/editor/agent
+npm run typecheck
+npm run check:encoding
+git diff --check
+```
+
+浏览器 smoke：
+
+```text
+打开 /editor/agent
+创建模板项目
+提交一次 AI patch
+等待静态构建成功
+确认 iframe 展示新预览
+提交一次故意破坏构建的 patch
+确认错误出现且上一版预览仍保留
+刷新页面确认项目、日志和 active preview 可恢复
+```
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index 3909dc66d..8130008e1 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -59,7 +59,8 @@ npm run check:server-rs-ddd
 - 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
 - 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
 - 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
-- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`。
+- 外部 OpenAPI：`/api/external/v1/openapi.json`、`/api/external/v1/assets/direct-upload-tickets`、`/api/external/v1/assets/objects/confirm`、`/api/external/v1/assets/read-url`、`/api/external/v1/editor/*`，使用 Bearer API Key 鉴权；API Key 管理仍在登录态 `/api/profile/api-keys`，不进入外部 OpenAPI JSON。
+- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`、`/api/editor/projects*`。
 - 后台入口配置：`/admin/api/creation-entry/config`、`/admin/api/creation-entry/config/banners` 和 `/admin/api/creation-entry/config/interactions`。
 - 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
 - 拼图：`/api/runtime/puzzle/*`。
@@ -199,10 +200,10 @@ npm run check:server-rs-ddd
 
 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5` Responses / Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/responses`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
 - 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
-- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
-- Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
+- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
+- Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
-- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 真实透明 alpha PNG 并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物上传 OSS 前不做服务端抠图后处理，避免误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
+- 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物和返回按钮上传 OSS 前只做服务端绿幕去背后处理，避免泛抠图误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
 - 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；前端选择或录音阶段只在浏览器本地处理待提交音频，统一限制裁切后最长 1 秒、裁掉前后声音过小片段，并用浏览器端近似响度算法平衡到 `-15 LKFS` 后做峰值保护。点击生成时才直传 OSS 并确认 `asset_object`，创作 JSON 只提交轻量 `WoodenFishAudioAsset`，不得继续上传 Data URL 音频；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。前端如果收到同一 OSS bucket 的完整 `https://*.oss-*.aliyuncs.com/generated-*` 地址，也必须先归一为 legacy path 后走同一换签链路，避免裸连私有 bucket 403 或绕过签名缓存。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`；旧对象若缺该头，只能依赖 `ETag` / `Last-Modified` 协商缓存，应通过 OSS 元数据刷新或 CDN 配置补齐，不要恢复 api-server 静态代理。
@@ -429,6 +430,48 @@ npm run check:server-rs-ddd
 - Rust 结构体：`DatabaseMigrationOperator`
 - 源码：`server-rs/crates/spacetime-module/src/migration.rs`
 
+### `external_api_key`
+
+- Rust 结构体：`ExternalApiKey`
+- 源码：`server-rs/crates/spacetime-module/src/external_api_key_storage.rs`
+- 说明：外部 OpenAPI 调用使用的账号级 API Key 凭据表，只保存 key prefix、SHA-256 hash、作用域、撤销状态和使用时间；明文 Key 只在 `/api/profile/api-keys` 创建接口返回一次，不进入 SpacetimeDB，且 API Key 管理接口不写入外部 OpenAPI JSON。v1 默认作用域为 `editor:project`、`editor:canvas`、`editor:image-generate`、`editor:asset`；其中 `editor:project` 覆盖项目列表、最近项目、创建、读取、重命名和删除，`editor:canvas` 覆盖默认画布布局保存，`editor:image-generate` 覆盖编辑器现有图片生成、重绘 / 调整、规范图、宣发素材、图标 spritesheet 生成 / 拆分、UI 设计图素材拆分、角色动画、视频、音效和背景音乐生成，`editor:asset` 覆盖素材直传凭证、素材对象确认、签名读取、账号级素材库和项目画布资源记录操作。
+- 索引：`by_external_api_key_owner_user_id` 用于登录态 API Key 列表；`key_hash` 唯一索引用于外部 API 鉴权。
+
+### `editor_project`
+
+- Rust 结构体：`EditorProject`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布工程真相表，保存 owner、标题和工程时间戳；viewport 与图层布局已拆到 `editor_canvas`，旧 layout columns 暂作为兼容列保留，不再作为权威数据源。只通过 `/api/editor/projects*` BFF 和 `spacetime-client` facade 读写；项目页列表、重命名和删除也使用该能力，删除工程时级联清理默认画布和资源元数据。
+- 索引：`by_editor_project_owner_user_id` 用于读取当前用户最近编辑工程和项目页工程列表。
+
+### `editor_canvas`
+
+- Rust 结构体：`EditorCanvas`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布数据表，归属于 `editor_project`，保存默认画布的 viewport typed columns、图层布局 JSON、owner 和时间戳；当前编辑器读取 / 保存 project 的默认 canvas，后续支持一个工程多个 canvas。
+- 索引：`by_editor_canvas_project_id`、`by_editor_canvas_owner_user_id`。
+
+### `editor_project_resource`
+
+- Rust 结构体：`EditorProjectResource`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布工程资源元数据表，保存已经放入某个 project 画布的上传 / 生成图片资源快照、OSS 引用、尺寸、来源类型、prompt、provider、task、源资源关系、`asset_kind` 和 `generation_inputs_json`。`asset_kind` 标记角色、图标、UI 设计图、视频、音频等素材类别；`generation_inputs_json` 保存用户可见生成输入快照，供图片信息页刷新后恢复。图片 / 图标 / UI 提取等生成 BFF 在请求携带 `project_id` 时负责创建该表记录并把 resource 快照返回前端；前端只保存布局引用，不能把同一生成结果再次作为正式业务真相写入。账号级素材删除不级联删除该表，避免历史画布丢图。`editor_canvas.layers_json` 只保存图层几何、层级、分组、资源引用和生成器对象；新写入不再把素材生成输入快照作为图层布局真相保存，旧布局字段只作为兼容兜底读取。
+- 索引：`by_editor_project_resource_project_id`、`by_editor_project_resource_owner_user_id`。
+
+### `editor_asset_folder`
+
+- Rust 结构体：`EditorAssetFolder`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布账号级素材文件夹表，归属于用户账号而不是 project；首次读取素材库时自动创建系统默认“项目素材”文件夹。文件夹支持重命名、折叠和删除，系统默认文件夹不能删除。
+- 索引：`by_editor_asset_folder_owner_user_id`。
+
+### `editor_asset`
+
+- Rust 结构体：`EditorAsset`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：图片画布账号级素材表，保存用户上传 / 生成素材的名称、文件夹、图片读取地址、OSS 引用、尺寸、来源类型、prompt、provider、task、`asset_kind` 和 `generation_inputs_json`。素材在同一账号的所有项目中可见；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `asset_folder_id` 时负责创建账号级生成素材并返回 asset 快照，前端只用该快照更新素材栏。素材放入画布时复制为 `editor_project_resource` 并由图层引用 resourceId，画布从 resource / asset 级元数据恢复素材类别和用户可见生成输入快照。
+- 索引：`by_editor_asset_owner_user_id`、`by_editor_asset_folder_id`。
+
 ### `inventory_slot`
 
 - Rust 结构体：`InventorySlot`
diff --git a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
new file mode 100644
index 000000000..f0a8aa06a
--- /dev/null
+++ b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md
@@ -0,0 +1,146 @@
+# 外部 OpenAPI 与 API Key 接入方案
+
+## 背景
+
+外部调用方需要通过稳定 HTTP 契约使用图片画布编辑器内的素材生成、编辑和管理能力，并能创建项目、保存画板布局和管理账号级素材库。该能力必须走 `server-rs + Axum + SpacetimeDB` 正式链路，不能把 API Key、画板状态、素材状态或生成结果放到前端临时状态中。
+
+## v1 范围
+
+本期新增外部 API 命名空间：
+
+```text
+/api/external/v1
+```
+
+v1 只开放以下能力：
+
+- `POST /api/external/v1/assets/direct-upload-tickets`：创建素材直传 OSS 凭证。
+- `POST /api/external/v1/assets/objects/confirm`：确认已上传素材对象，`ownerUserId` 固定为 API Key 所属账号。
+- `GET /api/external/v1/assets/read-url`：获取私有素材读取签名 URL。
+- `GET /api/external/v1/editor/projects`：列出当前 API Key 所属账号的图片画布项目。
+- `POST /api/external/v1/editor/projects`：创建图片画布项目。
+- `GET /api/external/v1/editor/projects/recent`：读取当前账号最近图片画布项目。
+- `GET /api/external/v1/editor/projects/{projectId}`：读取项目与默认画布。
+- `PATCH /api/external/v1/editor/projects/{projectId}/metadata`：更新图片画布项目标题。
+- `DELETE /api/external/v1/editor/projects/{projectId}`：删除图片画布项目，并级联清理默认画布和项目资源元数据。
+- `PATCH /api/external/v1/editor/projects/{projectId}/canvas`：保存默认画布的 viewport 和 layers。
+- `POST /api/external/v1/editor/projects/{projectId}/resources`：创建项目画布资源记录。
+- `GET /api/external/v1/editor/assets/library`：读取账号级编辑器素材库。
+- `POST /api/external/v1/editor/assets/folders`：创建素材文件夹。
+- `PATCH /api/external/v1/editor/assets/folders/{folderId}`：更新素材文件夹名称或折叠状态。
+- `DELETE /api/external/v1/editor/assets/folders/{folderId}`：删除素材文件夹并返回最新素材库。
+- `POST /api/external/v1/editor/assets`：创建素材记录。
+- `PATCH /api/external/v1/editor/assets/{assetId}`：更新素材名称或所在文件夹。
+- `DELETE /api/external/v1/editor/assets/{assetId}`：删除素材记录。
+- `POST /api/external/v1/editor/images/generations`：调用编辑器图片素材生成能力；通过 `kind` 支持普通图、规范图 `spec`、角色图 `character`、快速编辑参考图 `quick-edit`、UI 设计图 `ui-design` 和宣发素材 `publication-material`。可选传入 `projectId` 和 `assetFolderId`，生成后按站内编辑器规则写入 `editor_project_resource` 和账号级 `editor_asset`。
+- `POST /api/external/v1/editor/images/edits`：重绘 / 调整已有图片，结果可写入项目资源和素材库。
+- `POST /api/external/v1/editor/icon-spritesheets/generations`：按规范图生成图标 spritesheet，并拆分为独立图标素材。
+- `POST /api/external/v1/editor/ui-designs/assets/extractions`：从 UI 设计图中提取 / 拆分素材。
+- `POST /api/external/v1/editor/character-animations/generations`：基于角色图片生成角色动画预览和帧序列。
+- `POST /api/external/v1/editor/videos/generations`：生成编辑器视频素材，支持现有 Seedance / Kling / Veo 模型参数和参考媒体限制。
+- `POST /api/external/v1/editor/audios/sound-effects/generations`：生成编辑器音效素材。
+- `POST /api/external/v1/editor/audios/background-music/generations`：生成编辑器背景音乐素材。
+- `GET /api/external/v1/openapi.json`：导出本版本 OpenAPI 3.1 JSON。
+
+管理 API Key 的登录态接口保留在站内个人中心链路，但不写入外部 OpenAPI JSON：
+
+```text
+GET    /api/profile/api-keys
+POST   /api/profile/api-keys
+DELETE /api/profile/api-keys/{keyId}
+```
+
+前端入口位于登录后个人中心的 `我的 → 开发者 API Key`，用于查看当前 Key、创建新 Key、复制一次性明文和撤销已创建 Key。外部 OpenAPI 只描述 `/api/external/v1` 下可由 API Key 调用的接口，不混入登录态 API Key 管理接口。
+
+## 鉴权
+
+外部调用使用 Bearer API Key：
+
+```http
+Authorization: Bearer tnr_sk_xxx
+```
+
+规则：
+
+- API Key 归属于 `owner_user_id`，外部接口只能访问该账号自己的项目、画布和生成素材。
+- 明文 Key 只在创建接口返回一次，后端只保存 `key_hash` 与 `key_prefix`。
+- API Key 被撤销后立即不可再用于外部接口。
+- 外部 API 鉴权不复用登录态 JWT，不检查 refresh session；它是独立开发者凭据。
+- OpenAPI JSON 公共可读，不需要鉴权。
+
+## 数据模型
+
+新增 SpacetimeDB private 表：
+
+```text
+external_api_key
+```
+
+字段：
+
+- `key_id`：主键。
+- `owner_user_id`：所属账号。
+- `name`：用户可识别名称。
+- `key_prefix`：前缀片段，用于列表展示和排障。
+- `key_hash`：完整 Key 的 SHA-256 十六进制摘要，唯一。
+- `scopes_json`：作用域 JSON，v1 固定包含 `editor:project`、`editor:canvas`、`editor:image-generate`、`editor:asset`。其中 `editor:image-generate` 覆盖图片生成、重绘、规范图、宣发图、图标拆分、UI 素材拆分、角色动画、视频、音效和音乐生成。
+- `created_at` / `last_used_at` / `revoked_at` / `updated_at`。
+
+SpacetimeDB procedure：
+
+- `create_external_api_key_and_return`
+- `list_external_api_keys_and_return`
+- `revoke_external_api_key_and_return`
+- `authenticate_external_api_key_and_return`
+
+## 素材生成与落库
+
+外部生成接口复用站内编辑器已有 handler 和 DTO，不维护第二套生成语义：
+
+- 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则。
+- 图标 spritesheet 和 UI 设计图素材提取复用站内拆分逻辑，生成图集后按连通域切片，并把图集与切片都按请求写入项目资源和素材库。
+- 角色动画、视频、音效和背景音乐复用站内编辑器生成链路；音频类外部调用使用 API Key 所属账号作为 asset owner。
+- API Key 管理接口仍只属于登录态个人中心，不进入外部 OpenAPI JSON。
+
+图片类外部生成成功后，后端拿到素材后：
+
+1. 通过 OSS / asset object adapter 持久化图片。
+2. 写入 `editor_asset`，让生成图进入账号级素材库。
+3. 如果请求带 `projectId`，写入 `editor_project_resource`。
+4. 返回图片读取地址、素材 ID、资源 ID、尺寸、prompt、model、provider 和 taskId。
+
+如果请求未带 `projectId`，只生成并写入素材库；调用方可随后创建项目或自行保存画板布局。
+
+## 素材与项目资源操作
+
+外部素材操作复用站内图片画布素材库和项目资源的后端事实源：
+
+- 外部上传素材时先调用 `POST /api/external/v1/assets/direct-upload-tickets` 获取 OSS 表单直传参数，上传完成后调用 `POST /api/external/v1/assets/objects/confirm` 写入 `asset_object`，再用 `assetObjectId` / `objectKey` 创建账号级素材或项目资源记录。
+- 外部读取私有 generated / uploaded 素材预览时调用 `GET /api/external/v1/assets/read-url` 获取短期签名 URL；不开放浏览器 STS 写权限。
+- 素材库读取、文件夹创建 / 更新 / 删除、素材创建 / 更新 / 删除、项目画布资源创建全部通过 `api-server -> spacetime-client -> spacetime-module`。
+- 所有外部素材接口使用 API Key 所属的 `owner_user_id`，不能由请求体传入 owner。
+- 素材库仍是账号级事实源，不归属于单个项目；项目画布内资源继续使用 `editor_project_resource`。
+- 素材创建和项目资源创建接口只保存记录和元数据；图片二进制上传、签名读取和生成图持久化继续复用已有资产 / 生成链路。
+
+## OpenAPI 导出
+
+OpenAPI 3.1 JSON 固定落在：
+
+```text
+docs/openapi/genarrative-external-v1.openapi.json
+```
+
+服务端 `GET /api/external/v1/openapi.json` 使用同一份 JSON，通过 `include_str!` 导出，避免运行时生成结果与仓库文档漂移。
+
+## 验收
+
+- API Key 创建只返回一次明文，列表不返回明文。
+- 撤销后的 API Key 调用外部接口返回 `401`。
+- 外部图片生成、重绘、图标拆分和 UI 素材拆分成功后，生成结果按请求同时出现在画布资源和账号级素材库。
+- 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
+- OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
+- OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。
+- 外部素材库接口覆盖当前已有素材操作：直传凭证、素材对象确认、签名读取、读取素材库、创建 / 更新 / 删除文件夹、创建 / 更新 / 删除素材、创建项目画布资源。
+- 外部项目接口覆盖当前已有项目管理操作：项目列表、最近项目、创建、读取、重命名、删除和默认画布保存。
+- 外部素材生成接口覆盖当前已有编辑器素材操作：生图、重绘 / 调整、规范图生成、宣发素材生成、图标素材生成与拆分、UI 设计图生成与拆分、角色动画、视频、音效和背景音乐。
+- 修改 SpacetimeDB schema 后运行 `npm run spacetime:generate` 与 `npm run check:spacetime-schema`。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index c0d215704..9d02a67b0 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -49,6 +49,8 @@ Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模
 
 后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run dev:api-server` 并检查 `/healthz`；需要确认实例可接生产流量时检查 `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
 
+Windows 本地 `npm run dev` / `npm run dev:api-server` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。
+
 开发态 `npm run dev` 与 `npm run dev:api-server` 会默认注入 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，因此密码登录在本地开发环境可直接注册未知手机号账号；生产环境仍按 `api-server` 配置默认关闭该开关。
 
 本地 `npm run dev` 和 `npm run dev:api-server` 默认保留 inline 开发体验：未显式设置 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，外部生成 handler 会同步复用 worker executor，完成后返回 `completed`，便于快速确认 provider、OSS 和 SpacetimeDB 写回链路。inline 不创建 `external_generation_job`，也不能验证 worker lease、队列等待展示或动态扩缩容。
diff --git a/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
new file mode 100644
index 000000000..a8d98456b
--- /dev/null
+++ b/docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md
@@ -0,0 +1,208 @@
+# 创作主页与项目入口改版计划
+
+日期：2026-06-18
+
+## 背景
+
+当前平台首页中的“创作”仍偏向站内 Tab 和创作入口列表，“草稿”也仍作为一级入口存在。图片画布项目已经成为独立项目资产，需要在桌面端给用户一个更明确的创作工具主页，并把项目管理提升为一级入口。
+
+本轮改版参考外部创作工具首页的信息组织，但所有用户可见文案、测试命名和产品命名都使用“陶泥儿”。外部品牌只作为设计参考，不进入产品 UI、测试名或文档验收口径。
+
+## 目标
+
+- 新增桌面端独立 `/creation` 创作工具主页。
+- 桌面端直接打开站点首页 `/` 时默认展示新版创作主页内容；移动端继续保持原推荐首页。
+- 顶级导航中“创作”进入 `/creation`，“草稿”改为“项目”并进入 `/project`。
+- 移动端隐藏“创作”和“项目”入口，只保留浏览和个人相关入口。
+- 登录后在创作主页展示最近项目，并通过新建项目进入 `/editor/canvas?projectid=xxx`。
+- `陶泥儿精选` 展示真实账号素材瀑布流，不使用 mock 素材。
+- 现有 `/creation/<play>` 玩法工作台、草稿、作品架、生成恢复和发布链路保持不变。
+
+## 页面结构
+
+### 顶部品牌区
+
+- 标题：`陶泥儿 - 开启全民精品游戏创作`
+- 主按钮：`开始创作`
+- 社群入口：原地弹出“玩家社区”二维码弹窗，复用现有社区弹层能力，不跳转或切换到“我的 / 用户中心”。
+- 营销点：`登录即送100泥点，可以免费制作50个素材`
+
+`开始创作` 与“新建项目”使用同一项目创建链路。用户已登录时调用现有 `createEditorProject`，成功后进入 `/editor/canvas?projectid=xxx`；未登录或登录过期时打开登录弹窗，并在登录后重试创建。
+
+该区是页面第一屏的品牌与主操作区域，不使用外站品牌名。桌面端 `/creation` 继续保留现有平台左侧导航栏和上方栏，创作主页只替换中间内容区。
+
+### 九大创作工具能力
+
+创作主页展示九项能力，用于说明陶泥儿创作工具覆盖范围：
+
+1. 游戏视觉规范：轻松约束多类素材视觉一致性。
+2. 游戏角色：整套高完成度 2D / 3D 角色素材及动画。
+3. 游戏 UI：轻松生成高一致性的 UI 素材。
+4. 游戏音乐：轻松制作游戏背景音乐、音效。
+5. 游戏特效：低成本生成精品游戏特效。
+6. 游戏场景：轻松生成各类游戏场景素材。
+7. 游戏美宣：轻松生成游戏上架所需图片和视频。
+8. 游戏功能编码：自然语言驱动游戏生成。
+9. 一键导出：支持一键导出为微抖小游戏、Godot、Unity、UE 工程。
+
+### 最近项目
+
+仅登录后展示。模块位置在“陶泥儿精选”上方。
+
+- 标题：`最近项目`
+- 标题右侧：`查看全部`，跳转 `/project`
+- 左侧第一项：`新建项目`
+- 右侧项目卡：按 `updatedAt` 倒序展示最近 4 个项目。
+- 项目卡点击进入 `/editor/canvas?projectid=xxx`。
+- 项目卡点击必须直接写入最终 `/editor/canvas?projectid=xxx` 历史项，不允许先进入无参数 `/editor/canvas` 再二次跳转，否则浏览器返回需要点两次。
+- 项目缩略图复用 `/project` 项目卡的画布中心封面逻辑，避免两套封面算法。
+
+未登录状态不展示最近项目区，避免空态文案占据首屏。
+
+### 陶泥儿精选
+
+`陶泥儿精选` 是页面底部的用户素材瀑布流，不承载玩法入口列表。瀑布流卡片按真实素材宽高设置预览比例，同一行允许出现不同高度卡片，不使用固定等高网格。创作入口配置仍继续来自 `/api/creation-entry/config`，供旧创作入口和具体 `/creation/<play>` 工作台使用，但不作为本页精选区内容。
+
+精选内容优先使用真实账号级素材和生成结果数据；未登录或账号素材为空时，可使用已公开作品中真实用户生成的图片作为瀑布流素材来源。两种来源都不使用 mock。若现有数据缺少提示词、作者名或成本字段，v1 显示保守占位，不伪造内容。
+
+Tab：
+
+- 素材包
+- 角色
+- UI
+- 音乐
+- 特效
+- 场景
+- 美宣
+- 游戏
+
+展示口径：
+
+- 素材包：每个列表项展示同一规范图生成的规范图和相关素材组合。
+- 角色：每个列表项展示游戏角色图和该角色生成的角色动画素材组合。
+- UI：每个列表项展示游戏 UI 图和该 UI 图拆出的子素材组合。
+- 音乐：展示背景音乐和音效。
+- 美宣：展示美宣类图片和视频素材。
+- 特效、场景、游戏：v1 暂不实装生成链路，只在有真实数据时展示，无数据时不造假卡片，也不在 UI 中写“暂不实装”说明。
+
+交互口径：
+
+- 点击任一精选列表项后打开接近全屏的素材预览弹窗。
+- 弹窗中部展示当前素材，图片使用 contain 完整展示，视频和音频展示可播放控件。
+- 弹窗底部固定显示当前组合的缩略图导航，点击缩略图切换当前素材。
+- 弹窗底部同时展示该列表项的提示词、作者名和生成总成本。
+
+每个列表项需要标注：
+
+- 提示词
+- 作者名
+- 生成总成本，单位为泥点
+
+数据来源：
+
+- 图片类素材优先读取账号级素材库和已落库生成结果。
+- 未登录或账号素材为空时，读取已公开作品中的真实用户生成图片作为精选素材补充，但卡片仍按素材瀑布流呈现，不展示玩法入口卡。
+- 音乐、音效、视频类素材只展示已存在的真实记录。
+- 不为了填满展示区创建假素材、假作者、假泥点成本或假组合关系。
+- 暂无真实数据的 Tab 保留 Tab 入口，但内容区显示简洁空态。
+
+## 数据与状态边界
+
+- `/creation` 是创作工具主页，不承接正式玩法业务真相。
+- 创作入口配置继续从 `/api/creation-entry/config` 读取。
+- 最近项目继续使用编辑器项目接口：`listEditorProjects`、`createEditorProject` 和 `/editor/canvas?projectid=xxx`。
+- 最近项目和项目页打开画布时，浏览器 history 只保留带 `projectid` 的最终画布路由。
+- 项目封面逻辑复用 `/project` 项目卡已有的画布中心缩略图算法。
+- `陶泥儿精选` 读取账号级素材库；若字段缺失，前端只显示空值或隐藏对应元信息，不在前端推导业务真相。
+- `/creation/<play>` 的玩法工作台、草稿、生成页、结果页、发布、运行态和作品架链路保持原状。
+
+## 路由与导航
+
+- 新增 `SelectionStage = 'creation-home'`。
+- `/creation` 映射到 `creation-home`。
+- 桌面端初始打开 `/` 时也进入 `creation-home`；移动端初始打开 `/` 仍进入 `platform` 推荐首页。
+- `/creation/<play>` 现有玩法工作台路由保持原有 stage 映射。
+- 桌面端点击“创作”时调用 `pushAppHistoryPath('/creation')`。
+- 桌面端原“草稿”入口改为“项目”，点击 `pushAppHistoryPath('/project')`。
+- 桌面端平台一级页统一复用 `/creation` 的平台桌面 chrome，保留左侧完整导航栏和右侧顶部栏；推荐、发现、我的、`/creation` 与 `/project` 只替换右侧主内容区，不能作为脱离导航的独立全屏页渲染，避免用户进入任一页后无法返回或切换页签。
+- 桌面端从 `/creation` 切换到 `/project` 后，“项目”页签进入选中态，“创作”页签必须恢复为普通默认态，不保留创作主页的主按钮强调表现。
+- `/project` 项目页头部必须提供 `返回主站` 按钮，点击后切回平台首页 `/`，行为与桌面侧栏切回推荐页保持一致。
+- 移动端导航列表不展示“创作”和“项目”。
+- 移动端不拦截用户直接访问 `/creation` 或 `/project`。
+
+## 实施拆分
+
+### 路由与导航
+
+- 增加 `/creation` 路由映射和测试。
+- 增加桌面 `/` 初始阶段映射测试，确认不会影响移动端首页。
+- 调整桌面导航文案与点击行为。
+- 移动端导航移除“创作”和“项目”入口。
+- 保持现有 `/creation/<play>` 工作台、生成页、结果页和运行态路由不回归。
+
+### 创作主页
+
+- 新增 `CreationLandingView`。
+- 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选素材瀑布流。
+- 桌面端复用现有平台壳层，保留上方栏和左侧导航栏。
+- 主页整体采用浅色布局，避免外站品牌文案。
+- 视觉排版参考陶土质感创作工具工作台：首屏标题居中、主按钮与社区按钮使用大号圆角胶囊尺寸，九大创作工具以 3 列大卡片展示，卡片左侧保留大号陶土感图标区域，右侧展示原有标题与描述；桌面平台一级页的顶部栏和左侧导航统一压平成单层工作台 chrome，避免外框套内框；桌面端页面结构必须先分为“左侧完整栏 / 右侧内容区”，左侧完整栏同时包含顶部品牌 Logo 和下方导航页签，右侧内容区再拆为顶部搜索、钱包、账号栏与下方主屏，不能用顶部栏的第一列假装左侧品牌区；左侧栏采用紧凑但保留图标和文字的导航胶囊，顶部搜索栏、泥点入口和账号入口都保持精简宽度，提升推荐、发现、我的、创作主页和项目页的工具感与精致度；只调整样式与布局，不改文案、搜索、登录、导航、项目创建、社区弹层、最近项目、精选素材 Tab 或数据读取逻辑。
+- 背景、顶部品牌小陶偶、左侧导航、按钮和九大创作工具图标使用 `gpt-image-2` / image2 生成资源，统一保存在 `public/creation-home/`；资源只作为装饰图标或背景纹理接入，不包含图内文字，不替换或隐藏现有 UI 文案和交互。
+- 社群入口复用现有玩家社区弹层，点击后必须停留在 `/creation`。
+- 不在 UI 中放规则说明、实现说明或“暂不实装”提示。
+- 未登录时不渲染最近项目区；需要创建项目时走登录弹窗和登录后重试。
+
+### 项目卡与封面复用
+
+- 从 `ProjectGalleryView` 抽出项目封面模型或组件。
+- `/creation` 最近项目与 `/project` 共用同一封面逻辑。
+- 新建项目复用现有 `createEditorProject`、`listEditorProjects` 和 `/editor/canvas?projectid=xxx` 链路。
+
+### 我的页
+
+- 删除“项目 / 画布项目”快捷入口。
+- 常用功能区稳定为 4 项：泥点充值、兑换码、玩家社区、反馈与建议。
+
+## 测试计划
+
+单元和组件测试：
+
+- `appPageRoutes.test.ts`：覆盖 `/creation -> creation-home`，并确认现有 `/creation/<play>` 不回归。
+- `RpgEntryHomeView.recharge.test.tsx`：桌面显示“创作”“项目”，不显示“草稿”；移动端不显示“创作”和“项目”；我的页不再出现项目快捷入口。
+- `CreationLandingView.test.tsx`：覆盖首屏主视觉、九大功能、最近项目、新建入口、查看全部、未登录隐藏最近项目、素材 Tab。
+- `PlatformEntryFlowShellImpl` 相关测试：点击“创作”进入 `/creation`，点击“项目”进入 `/project`，项目页头部“返回主站”回到 `/`，新建项目进入 `/editor/canvas?projectid=xxx`。
+- `ProjectGalleryView.test.tsx`：封面抽取后项目封面、头部“返回主站”、重命名、删除和选择模式保持通过。
+
+验证命令：
+
+```bash
+npm run test -- src/routing/appPageRoutes.test.ts src/components/project/ProjectGalleryView.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
+npm run typecheck
+npm run check:encoding
+git diff --check
+```
+
+浏览器回归：
+
+- 桌面打开站点首页 `/`，首屏显示新版创作主页。
+- 桌面打开首页，点击“创作”进入 `/creation`。
+- `/creation` 显示 `陶泥儿 - 开启全民精品游戏创作` 和 `陶泥儿精选`。
+- 页面不出现外站品牌或 `Discord` 字样。
+- 未登录时最近项目区不展示，点击“开始创作”弹登录。
+- 登录后显示最近项目、新建项目、最多 4 个项目和“查看全部”。
+- 点击新建项目进入 `/editor/canvas?projectid=xxx`。
+- 桌面导航显示“项目”，不显示“草稿”。
+- `/project` 头部点击“返回主站”回到 `/`，并退出项目页主内容。
+- 移动视口底部不显示“创作”和“项目”。
+- “我的”页没有项目快捷入口。
+- 陶泥儿精选素材瀑布流不出现 mock 素材、假作者或假泥点成本。
+- 陶泥儿精选素材卡按真实素材宽高呈现瀑布流，不退化为固定等高网格。
+- 陶泥儿精选不出现玩法入口卡；即使使用公开作品图片补充展示，也必须呈现为用户素材瀑布流。
+
+## 非目标
+
+- 不新增后端接口。
+- 不删除现有玩法草稿、作品架、生成恢复、发布或运行态能力。
+- 不恢复前端硬编码创作入口配置。
+- 不用 mock 素材填充用户素材展示。
+- 不在移动端禁止直接 URL 访问 `/creation` 或 `/project`。
diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
index ac3104e60..7b01094e4 100644
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -139,7 +139,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 前端创作、结果页、生成页和错误提示不展示 GPT / Gemini 等具体模型名称；如需在内部保留模型路由，UI 只使用“标准模式”“创意模式”等产品化名称。
 - 若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 `getPuzzleAgentSession(sessionId)`；只有最新 session 仍缺 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
 - 拼图参考图 AI 重绘走 VectorEngine `/v1/images/edits`；无参考图时走 `/v1/images/generations`。两者模型都使用 `gpt-image-2`，参考图由后端作为 multipart `image` part 传入编辑接口。
-- 每次新建关卡生成或重新生成关卡图都必须由 `api-server` 串起当前关卡资产包：AI 重绘开启时第一段沿用草稿生成第一关的拼图主图提示词配置和模型 / 尺寸 / 参考图规则生成 `coverImageSrc/coverAssetId` 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 `1:1`；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 `sourceType=uploaded` 的正式候选。随后用正式候选图作为参考，`9:16` 生成完整拼图游戏关卡画面并写入 `levelSceneImageSrc/levelSceneImageObjectKey`，提示词必须要求道具按钮上不要显示次数标注，且返回按钮和设置按钮旁禁止标注文字；UI spritesheet 与关卡纯背景在关卡画面完成后并发生成，spritesheet 用 `1:1`、`1k` 先生成纯绿色绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16`、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。
+- 每次新建关卡生成或重新生成关卡图都必须由 `api-server` 串起当前关卡资产包：AI 重绘开启时第一段沿用草稿生成第一关的拼图主图提示词配置和模型 / 尺寸 / 参考图规则生成 `coverImageSrc/coverAssetId` 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 `1:1`；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 `sourceType=uploaded` 的正式候选。随后用正式候选图作为参考，`9:16` 生成完整拼图游戏关卡画面并写入 `levelSceneImageSrc/levelSceneImageObjectKey`，提示词必须要求道具按钮上不要显示次数标注，且返回按钮和设置按钮旁禁止标注文字；UI spritesheet 与关卡纯背景在关卡画面完成后并发生成，spritesheet 用 `1:1`、`1k` 先生成单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16`、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。
 - 结果页允许多关卡并行编辑和生成；某一关卡图片生成完成回包只静默更新该关卡素材与生成态，不得自动打开或切换关卡详情面板，避免打断用户正在编辑的其它关卡。
 - 结果页关卡图片生成只标记对应关卡的局部生成进度，不禁用“新增关卡”、其它关卡详情编辑和结果页导航。
 - 结果页单关测试只能把完整草稿持久化，并通过 `levelId` 指定运行态起始关卡；不得把单关快照作为整份草稿调用 `updatePuzzleWork`，否则 source session 和作品 profile 的 `levels` 会被覆盖成单关，退出重进后其它关卡会丢失。
@@ -219,7 +219,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 3. `功德有什么`：最多 8 条飘字，创作态首屏只保留一个默认词条 `幸运`，其下提供加号格继续追加词条；创作态只保存词条名，运行态飘字展示时再追加 `+1`。运行态顶部总数卡采用品牌化徽标样式，子项计数器预置展示在可展开面板中，未出现词条初始值为 0。
 4. `作品标题 / 作品简介 / 主题标签`：不再放在创作工作台首屏，改为生成草稿后的结果页补录区，提交试玩或发布前必须先写回当前作品信息。主题标签编辑样式对齐拼图结果页的胶囊标签编辑器。
 
-图片生成链路固定为三图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 `1:1` 绿色背景主体图（纯绿色绿幕），prompt 必须显式要求背景为单一纯绿色 `#00FF00` 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，且禁止黑底、白底、棋盘格和任何实底背景；后端在落库前只对这张绿幕主体图执行去绿背景处理，不做泛抠图，避免误伤玉米等主体像素。第二步必须使用第一步抠图完成后的透明图作为参考图，再用新敲击物作为主题和画风参考生成 `9:16` 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品；画面中央主体预留区必须干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围。第三步必须使用去绿后的敲击物主体图和背景环境图作为参考图生成 `1:1` 返回按钮图，返回按钮必须始终是标准圆形，主体视觉尺寸比当前模板再放大约 50%，圆形外沿必须有与主题色搭配的干净外描边，中央只保留单个左箭头，参考图只约束圆形底色和箭头配色，不得延伸到复杂造型和花纹；按钮不得出现文字、数字、水印、额外 UI 面板或木槌物品。三个资产分别写回 `hitObjectAsset`、`backgroundAsset` 与 `backButtonAsset`，并绑定到 `wooden_fish_work` 的 `hit_object` / `background` / `back_button` 槽位。运行态和结果页消费 `backgroundAsset` 做竖屏背景，中央再叠加 `hitObjectAsset`，左上角返回按钮消费 `backButtonAsset`。
+图片生成链路固定为三图 image2 流程：第一步用默认木鱼图作为结构和画风参考，按用户题材关键词或参考图主题生成 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，prompt 必须显式要求背景严格使用该固定色且平整无纹理、无渐变、无阴影、无道具，主体完整居中，且禁止黑底、白底、棋盘格和任何实底背景；后端在落库前只对这张绿幕主体图执行去绿背景处理，不做泛抠图，避免误伤玉米等主体像素。第二步必须使用第一步抠图完成后的透明图作为参考图，再用新敲击物作为主题和画风参考生成 `9:16` 背景环境图，背景图只适配主题和画风，不能包含新敲击物本体，也不能增加木槌互动物品；画面中央主体预留区必须干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围。第三步必须使用去绿后的敲击物主体图和背景环境图作为参考图生成 `1:1` 返回按钮图，返回按钮必须始终是标准圆形，主体视觉尺寸比当前模板再放大约 50%，圆形外沿必须有与主题色搭配的干净外描边，中央只保留单个左箭头，参考图只约束圆形底色和箭头配色，不得延伸到复杂造型和花纹；按钮不得出现文字、数字、水印、额外 UI 面板或木槌物品。三个资产分别写回 `hitObjectAsset`、`backgroundAsset` 与 `backButtonAsset`，并绑定到 `wooden_fish_work` 的 `hit_object` / `background` / `back_button` 槽位。运行态和结果页消费 `backgroundAsset` 做竖屏背景，中央再叠加 `hitObjectAsset`，左上角返回按钮消费 `backButtonAsset`。
 
 木鱼初始 `compile-draft` 是长耗时同步 action，生成页必须按上述三图 image2 链路展示进度：整理草稿、生成敲击物、生成背景环境图、生成返回按钮图、写入正式草稿。本地或供应商慢时一次 action 可能持续数分钟；前端不得把已关闭的提示词生成音效当成进度阶段，也不得在未收到 action 回包前宣称生成完成。
 
@@ -281,8 +281,8 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 2. 先写入可恢复草稿 profile，再执行文本计划、关卡整图生成、三张派生图生成、OSS 上传和素材解析；作品摘要在背景、UI spritesheet 或物品 spritesheet 未完整时下发 `generationStatus=generating`，完整后下发 `ready`，草稿完成条件不包含 `backgroundMusic`。
 3. 首次调用 VectorEngine `gpt-image-2`，无参考图，竖屏 `9:16`，生成完整抓大鹅关卡画面并持久化到 `generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey`。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮。
 4. 关卡整图完成后并发发起三次 `gpt-image-2` 编辑请求，三者都以关卡整图作为参考图：`1K`、`1:1` 的 UI spritesheet 写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`；`1K`、`9:16` 的背景图写入 `imageSrc/imageObjectKey`；`2K`、`1:1` 的物品 spritesheet 写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。
-5. UI spritesheet 提示词固定要求按从上到下、从左到右整理纯绿色绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容。
-6. 物品 spritesheet 固定 `10行*10列`、统一纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次解析并持久化 `20` 种物品，物品信息列表全部展示这 `20` 种；后端切 `generatedItemAssets[].imageViews[]` 时优先按透明 alpha 连通域识别真实素材矩形，再按原图从上到下、从左到右排序，每 `5` 个区域组成一个物品的五个形态；只有识别出的区域数量不足时才回退 `10*10` 固定网格。持久化单格映射元数据仍按 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1`。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
+5. UI spritesheet 提示词固定要求按从上到下、从左到右整理单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容。
+6. 物品 spritesheet 固定 `10行*10列`、统一单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；素材间距严格均匀分布，每一行包含两种物品，每种物品五个不同形态，物品来自参考图中心容器中的 2D 素材，严禁高相似度物品。新流程每次解析并持久化 `20` 种物品，物品信息列表全部展示这 `20` 种；后端切 `generatedItemAssets[].imageViews[]` 时优先按透明 alpha 连通域识别真实素材矩形，再按原图从上到下、从左到右排序，每 `5` 个区域组成一个物品的五个形态；只有识别出的区域数量不足时才回退 `10*10` 固定网格。持久化单格映射元数据仍按 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1`。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退。
 7. 前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet：UI 图先把识别出的透明素材矩形按行聚类，再在每一行内按横向 `x` 坐标排序，最后按返回、设置、方格、移出、凑齐、打乱顺序映射回原 UI 位置；不能只按全局 `y` 坐标排序，否则同一行素材上下略有错位时会把方格和底部道具按钮顺序打乱。物品图按检测顺序每 `5` 个区域组成一个物品的五个形态，最多 `20` 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片。
 8. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
 9. 当前抓大鹅音频生成关闭：入口无 `生成音效`，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递。
diff --git a/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md b/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md
new file mode 100644
index 000000000..300e045dd
--- /dev/null
+++ b/docs/【编辑器】宣发素材工具演示入口设计-2026-06-17.md
@@ -0,0 +1,78 @@
+# 宣发素材工具入口设计
+
+## 目标
+
+在 Web 图片画布编辑器底部工具栏新增 `宣发素材` 分组入口，用于生成游戏发布物料。点击具体工作流后，不打开说明弹窗，而是在画布内创建一个可拖拽的宣发素材生成卡片；卡片包含游戏名、游戏分类、一句话描述游戏三个输入框、参考图控件、尺寸信息和生成按钮。点击生成后走图片画布现有生图 BFF，按当前图片模型计费方案自动扣泥点，生成成功后把成品图片放回画布。
+
+Prompt 输入摘要与 Prompt 约束只作为内部生成契约维护，不在 UI 中默认暴露；真实生图请求会把结构化游戏输入和对应工作流约束合并为内部 Prompt。
+
+三个工作流的输入框默认提示统一为：游戏名 `马戏团午夜惊魂`，游戏分类 `非对称对抗`，一句话描述游戏 `神奇数字马戏团里，帕姆尼失控了，找到钥匙，开门逃离马戏团，千万别被抓住了`。提示只作为占位文案，用户未填写时不进入生图 Prompt。
+
+## 入口
+
+- 页面：`/editor/canvas`
+- 位置：底部 AI 画布工具栏
+- 工具：`宣发素材`，位于底部工具栏 `生成UI设计图` 按钮右侧。
+- 交互：点击工具后弹出独立浮层菜单，菜单项包括 `游戏首图`、`详情五图`、`运营海报`；点击菜单项后在画布中心创建对应工作流的生成占位卡片，卡片可拖拽，设置面板锚定在占位卡片下方。
+- 设置面板：三个工作流统一对齐生成角色面板结构，顶部为参考图横向槽，主体为游戏名、游戏分类、一句话描述游戏输入区，底部复用生成类面板的模型选择与生成按钮；生成按钮内显示当前模型对应泥点。
+- 标题：画布占位卡片左上角使用英文功能名，例如 `Home Image Generator`、`Detail Gallery Generator`、`Promo Poster Generator`，与其它生成卡片保持一致。
+
+## 三条独立工作流
+
+1. `publication-cover-image`
+   - 名称：游戏首图
+   - 输出：单张主视觉
+   - 尺寸：`720 x 540`
+   - 适用：推荐流、作品卡和首屏传播位
+
+2. `publication-detail-gallery`
+   - 名称：详情五图
+   - 输出：单张详情图；需要五图时由用户连续生成五次，保持同一参考摘要和输入信息
+   - 尺寸：`720 x 1280`，`9:16` 竖版
+   - 适用：作品详情、应用介绍和运营分发图组
+
+3. `publication-promo-poster`
+   - 名称：运营海报
+   - 输出：单张活动海报
+   - 尺寸：`1280 x 720`，`16:9` 横版
+   - 版式：右下角保留白色二维码留白方块，并在方块内部上方加入黑色小字提示“此处换上你的游戏二维码”
+   - 适用：社群、活动、渠道投放和运营节日位
+
+## 职责边界
+
+本功能边界只负责图片编辑器里的宣发素材生成：
+
+- 可以维护：工作流框架、Prompt 约束、参考图解析约束、图片后处理验收约束。
+- 已落地：画布内生成占位卡片、游戏名 / 游戏分类 / 一句话描述游戏结构化输入、参考图上传 / 从画布选择、尺寸标识、真实生图、按图片模型计费、成品回画布。
+- 详情五图：当前 UI 只有一个生成卡片，一次生成 1 张 `720 x 1280` 竖版详情图，单次按当前图片模型计费；需要五图时连续生成并复用同一游戏输入和参考图。
+- 不在 UI 暴露：Prompt 输入摘要、Prompt 约束预览、内部提示词拼接过程。
+- 暂不实现：作品发布状态、审核、分享渠道、远程 Genarrative 接口、作品架或广场能力。
+- 不修改：SpacetimeDB schema、前端发布页、作品发布系统。
+
+## 生成与计费
+
+- 前端生成请求统一通过 `/api/editor/images/generations`。
+- 宣发素材请求携带 `kind: publication-material` 与当前图片模型，后端对这个 kind 按归一后的图片模型计费方案扣泥点，不再使用固定价格。
+- `publication-detail-gallery` 不再携带 `candidateCount: 5`；后端仍兼容多候选请求，但当前宣发素材入口不主动批量生成。
+- 尺寸请求必须使用明确像素值：游戏首图 `720x540`、详情图 `720x1280`、运营海报 `1280x720`。VectorEngine 适配层对明确像素值保持原样透传；只有 `16:9`、`9:16`、`2k` 等比例 / 档位别名才走 provider 预设映射。
+- 参考图在提交 `/api/editor/images/generations` 前由前端压缩成适合生成理解的图片 Data URL，避免原图 Data URL 撑爆 JSON 请求体；后端该路由保留 `12MB` body limit 作为兼容兜底。
+- 扣费通过现有钱包资产操作封装执行；上游生成失败或未返回图片时按现有补偿逻辑退款。
+- 生成成功后，成品作为图片画布生成图层加入画布，并保留游戏输入和参考图摘要供图层信息使用。
+
+## 代码位置
+
+- 工具入口：`src/components/image-editor/ImageCanvasBottomToolbarView.tsx`
+- 菜单和生成卡片挂载：`src/components/image-editor/ImageCanvasGenerationComposerView.tsx`
+- 工作流状态：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`
+- 工作流内容模型：`src/components/image-editor/ImageCanvasPublicationMaterialsModel.ts`
+- 画布内生成卡片设置面板：`src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx`
+
+## 验证命令
+
+```bash
+npm run test -- src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/services/image-editor/editorProjectClient.test.ts
+cargo test -p platform-image vector_engine --manifest-path server-rs/Cargo.toml
+cargo test -p api-server editor_image_generation_accepts_reference_body_above_default_limit --manifest-path server-rs/Cargo.toml
+cargo check -p api-server --manifest-path server-rs/Cargo.toml
+npm run check:encoding
+```
diff --git a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
new file mode 100644
index 000000000..e71338372
--- /dev/null
+++ b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
@@ -0,0 +1,191 @@
+# 生成类面板 Lovart 统一改造方案
+
+日期：`2026-06-17`
+
+## 范围
+
+图片画布编辑器内以下生成类面板统一对齐 Lovart 式极简创作工具风格：
+
+- `生成图片`
+- `生成规范`
+- `生成角色形象`
+- `生成图标素材`
+- `生成UI设计图`
+- `生成视频`
+- `生成游戏音效`
+- `生成游戏背景音乐`
+- `生成角色动作`
+- `快速编辑`
+
+`角色动画生成面板` 同步纳入本次生成类面板交互统一：点击角色图只聚焦图层，不自动弹出底部重绘或角色动画面板；点击 `生成动画` 后像新建图片一样创建 `角色动作` 画布占位，面板跟随占位底部，参考图首行、单文本无边界、参数按钮向上弹出、生成按钮明确展示泥点。
+`快速编辑` 由选中图片后的浮动工具栏显式打开，面板结构、参考图首行、提示词输入区和底部参数 / 生成区对齐其它生成类面板。
+
+## 统一布局
+
+1. 参考图区域永远位于面板第一行。
+2. 参考图使用统一方形参考图图标组件，不再使用横向长卡：
+   - 普通参考图：灰蓝色图片图标。
+   - 规范参考图：紫色规范 logo。
+   - 图标规范：绿色图标。
+   - UI 图标规范：琥珀色图标。
+   - 视频参考图：深色视频图标。
+3. 角色规范参考图组件只展示一个方形参考图图标；图标内上方是规范 logo，下方固定短标 `角色规范`，不再展示绑定状态、来源说明或长标题。已有绑定图片的原始标题只作为可访问名称、悬浮 title 和图片信息回看使用。
+4. 参考图图标尽量少文字；必要文字写在图标块内或短标签内，不写规则说明。
+5. 已有参考图在鼠标悬停或键盘聚焦到对应参考图槽位时，右上角显示一个 `×` 删除按钮；鼠标不在槽位上时不显示。点击 `×` 只移除该参考图绑定，不触发来源菜单、不删除画布图片。
+6. 普通参考图支持连续追加：已有图缩略图后始终保留一个 `+` 入口。点击入口只弹出“从画布中选择 / 上传图片”来源选项，不再直接打开系统文件选择器；生成图片、生成视频、角色常规参考图等同类参考图入口都遵循同一交互。
+7. 单文本输入面板不显示文本框标题，用问题式 placeholder：
+   - 生成图片：`今天想生成什么画面？`
+   - 生成角色：`你希望角色如何设计？`
+   - 生成 UI：`你希望这个 UI 长什么样？`
+   - 生成视频：`你希望生成什么视频？`
+8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框。
+9. 生成规范下的角色规范、图标规范和自定义规范都使用同一生成类 shell：首行参考图区域、中央字段区、底部生成按钮区，不再出现缺首行参考区或单独 footer 样式。
+10. 快速编辑最多允许额外绑定 8 张参考图；原图始终自动作为最后一张隐式参考图提交，不占用额外参考图额度，也不在参考图条里固定展示 `图x`。
+
+## 参数交互
+
+画面比例、大小尺寸、模型、分辨率、时长等生成参数统一为 Lovart 式底部胶囊按钮：
+
+```text
+左下：[比例·尺寸 ˄]          右下：[模型 ˄] [生成12泥点]
+```
+
+- 面板内不显示 `画面比例`、`大小尺寸`、`模型` 等字段标题，只显示当前选择值。
+- 图片类面板把画面比例和大小尺寸合并成一个左下角选项框；视频面板把比例、时长、清晰度合并成一个左下角选项框；音效面板把 Vidu duration 合并成一个无标题左下角选项框。
+- 模型选项框和生成按钮位于右下角，模型胶囊紧贴生成按钮；音效固定显示 `Vidu`，背景音乐固定显示 `Suno`，两者均沿用模型按钮样式但不可点击。
+- 点击后以页面级浮层向上弹出独立选项面板；父级面板隐藏或销毁时，选项面板同步销毁。
+- 点击选项只更新字段和选中样式，不收起选项面板；再次点击当前参数按钮可收起。
+- 选项面板打开后，点击父级生成面板内任意非选项框、非触发按钮区域必须收起；点击选项面板自身仍保持打开，便于连续修改。
+- 弹出面板内可分组展示字段，点击某个选项只更新当前字段和选中样式，方便连续修改。
+- 模型子面板每行固定一个模型，不用方框包裹模型名；模型名不换行，前置对应模型类型图标，选中项在模型名后用对号标记。
+- 比例选项卡片内展示对应比例的线框。
+- 父级面板、底部选项框、弹出子面板字号保持一致。
+- 底部组合值使用 `·` 分隔；图片类左下角不留空格，统一为 `x:y·xK`，例如 `16:9·1K`；视频、角色动作等多参数仍显示为 `16:9 · 4秒 · 480p`。
+- 底部参数热区与生成按钮等高，默认不显示阴影；悬停显示轻量阴影；箭头默认向下，展开后旋转向上。
+- 底边栏中会在上方弹出二级选项的入口不再依赖点击展开。鼠标悬停到入口即可打开二级面板，鼠标离开入口和二级面板后自动收起；当前范围包括 `生成规范` 和 `生成音乐`。
+- 底边栏二级选项面板必须锚定到对应入口按钮本身，不使用屏幕居中或固定底部偏移；移动端窄屏下也应保持跟随入口位置。
+- 生成图片和生成视频文本输入框紧贴参考图下方，取消旧网格预留导致的空白高度。
+- 生成规范类图片固定使用 `16:9·2K · gpt-image-2`。这三个参数在面板底部沿用可编辑参数按钮的胶囊样式展示，但控件保持禁用不可点击，不提供比例、尺寸或模型修改入口。
+- 快速编辑默认从原图分辨率和模型初始化比例、尺寸和模型，但底部胶囊必须可点击修改；左下角统一显示 `x:y·xK`，右下角模型胶囊紧贴生成按钮。
+- 不再在底部常驻展开全部可选项。
+
+## 泥点显示
+
+- 本次消耗泥点必须显示在生成按钮内部。
+- 生成按钮内明确显示 `N泥点`，例如 `生成12泥点`、`生成40泥点`；不使用泥点图标替代文字。
+- 画板内所有会提交外部生成任务的生成按钮，价格都必须从模型定价配置函数推导，不允许在按钮文案或提交 payload 中散落固定泥点数字；修改 `ImageCanvasGenerationModel.ts` 与 `api-server/src/editor_generation_config.rs` 的同名定价配置后，按钮展示、前端提交的 `priceMudPoints` 和后端校验 / 扣费应同步变化。
+- 当前前端展示价统一收口在 `ImageCanvasGenerationModel.ts`：生成图片、生成角色、快速编辑、重绘、宣发素材走 `calculateEditorImageModelPrice` / `calculateEditorImageGenerationPrice`；生成图标素材走 `calculateEditorIconSpritesheetPrice`；生成 UI 设计图走 `calculateEditorUiDesignPrice`；生成规范走 `calculateEditorSpecGenerationPrice`；生成视频走 `calculateEditorVideoPrice`；角色动画走 `calculateCharacterAnimationPrice`；音效 / 背景音乐分别走 `calculateEditorSoundEffectPrice` / `calculateEditorBackgroundMusicPrice`。
+- 泥点配置统一收口到 `api-server` 的编辑器生成配置模块；前端只保留与后端配置同名的展示兜底，后续可接接口动态下发。当前不是运行时动态配置接口，若要后台改价实时影响前端，需要新增配置下发能力。
+- 生成图标素材面板提交 `POST /api/editor/icon-spritesheets/generations` 时必须携带 `priceMudPoints`，取同一份 `icon` 计费配置；后端用 `editor_generation_config` 校验，不允许绕过配置继续生成。
+- 生成视频、角色动画、音效和背景音乐提交时携带的 `priceMudPoints` 也必须由同一模型配置函数计算，后端按归一后的模型、清晰度、时长或音频模型重新计算并校验。
+- `提取素材` 是 UI 设计图工具栏动作，不是面板生成按钮；它固定使用 `gpt-image-2` 和图标素材拆分链路，后端响应里的 `priceMudPoints` 仍必须来自 `editor_generation_config`，不能写死。
+- 画板 UI 统一显示 `nanobanana2`，它代表上游真实模型 `gemini-3.1-flash-image-preview`；历史输入或旧布局中的 `nano-banana` 必须先归一为 `nanobanana2` 对应的真实模型 ID 后再提交和计费。定价表仍以真实模型 ID `gemini-3.1-flash-image-preview` 和 `gpt-image-2` 为准，别名不能作为新增正式模型绕过定价表。
+
+## 画布占位落点
+
+- 任何会创建“即将生成”画布占位的 Lovart 面板入口，都必须先生成对应 draft，再通过统一 placement 模型改写 placeholder，不能直接使用 draft 初始中心点。
+- 统一入口范围：生成图片、生成规范、生成角色形象、生成图标素材、生成视频、生成 UI 设计图、生成角色动作。
+- 避让对象：所有 `hidden !== true` 的画布图层，以及当前 active / inactive generation dialogs 中已有的 placeholder。
+- 避让间距：每个避让矩形向外扩 32px，保证新占位和已有图层 / 占位之间保留可见空隙。
+- 距离目标：以当前视口世界中心为目标点，在候选落点中选择距离最近且不重叠的位置；中心被占用时按相邻边、四角和外圈候选继续寻找。
+- 居中行为：调用 `openCanvasGenerationDialog(...)` 时写入避让后的 placeholder；随后调用 `centerViewportOnPlacement(...)`，让屏幕中心移动到新占位中心，并保持原 viewport scale。
+- 入口状态：新入口打开后设置对应 activeTool，清空画布选中、右键菜单、快速编辑、角色动画和其它生成来源选择状态；只切换当前面板，不删除已有生成占位。
+- 生成中的占位图允许通过键盘 `Delete` / `Backspace` 删除；不额外增加画布上的可见删除按钮。用户删除后，后续异步成功或失败回写不得重新创建该生成对象。
+- 待生成占位的空白样式按生成类型区分：视频使用视频图标和视频角标，角色形象使用角色图标和角色角标，角色动作使用角色动作图标和动作角标，音效使用音效图标和音效角标，背景音乐使用音乐图标和背景音乐角标。
+- 待生成占位的图标语义必须与底部入口或触发入口保持一致：生成图片用图片图标，生成规范用规范图标，生成角色形象用角色图标，生成图标素材用图标网格，生成 UI 设计图用应用窗口，宣发素材用宣发图标，快速编辑用闪光图标，不能默认全部回退为图片图标。
+- 图片类待生成占位尺寸必须与面板当前比例和尺寸同步：普通图片、角色形象、图标素材、UI 设计图按当前 `aspectRatio + imageSize` 计算像素尺寸；生成规范固定为 `16:9·2K`，占位为 `2048 x 1152`；宣发素材按 workflow 输出尺寸创建占位。
+- 视频待生成占位必须与面板当前比例和清晰度同步：默认 `16:9 · 480p` 为 `854 x 480`，切换比例、`720p` 或 `1080p` 后按比例和清晰度重算偶数宽度；调整参数时保持占位中心点不变。
+- 面板中用户修改比例、尺寸或清晰度后，已有空白待生成占位立即同步更新 `width / height / originalWidth / originalHeight`，且保持中心点不跳动。
+- 快速编辑点击生成后不在原图上播放生成中遮罩，而是立即创建独立 `Quick Edit Generator` 画布生成占位并播放生成中动画；生成成功后结果落在该占位框位置，失败时占位标记失败并恢复快速编辑面板。
+
+## 画布悬浮信息
+
+- 待生成占位图只有聚焦或生成中才显示高亮边框、左上角生成器名称和右上角原始尺寸；失焦后保留灰色占位块本体，不显示这些辅助信息。
+- 占位图的生成器名称 / 原始尺寸、图片图层右上角素材类型标签、查看信息按钮和悬浮尺寸标签都按 viewport 反向缩放，画布缩小时保持屏幕可读尺寸。
+- 查看信息按钮固定使用圆形 `i` 图标，不使用中括号、花括号或文本符号样式。
+- 视频 / 角色 / 角色动作 / 音效 / 背景音乐待生成占位的角标同样按 viewport 反向缩放，不随画布缩放变小。
+- 已生成角色图、角色动作图或其它生成结果图被点击时只选中图层并收起已有生成输入框；重绘、快速编辑和生成动画面板必须由对应工具栏按钮或右键菜单显式打开。
+
+## 画布保存
+
+- 生成占位图和生成器对话框不是临时浮层，必须作为画布布局数据保存。
+- 保存时在现有画布布局数组中追加 `itemType: "generation-dialog"` 项，记录生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和 `generatedLayerId`。
+- 生成成功后仍保留生成器快照；画布渲染优先用 `generatedLayerId` 锚定到成品图层，不再重复显示灰色占位框。
+- 图片、视频和音频生成结果都要写入账号级素材库；视频 / 音频结果由后端持久化到 OSS 并回传 `objectKey` / `assetObjectId`，前端保存素材库时一并记录，后续预览和再次加入画布走统一换签链路。
+- 刷新项目后，画布需要同时恢复图层、生成器快照和生成输入框跟随关系。
+
+## 第一版计费配置
+
+```text
+生成图片 / 生成角色形象 / 生成图标素材 / 生成UI设计图 / 宣发素材 / 快速编辑 / 重绘：nanobanana2 为 12 泥点，gpt-image-2 为 20 泥点
+生成规范：固定 gpt-image-2，5 泥点
+生成视频：seedance2.0-fast 为 480p 每秒 10 / 720p 每秒 20，不支持 1080p；seedance2.0 为 480p 每秒 12 / 720p 每秒 24 / 1080p 每秒 48；kling3.0 为 480p 每秒 15 / 720p 每秒 30 / 1080p 每秒 60；kling3.0-omni 为 480p 每秒 20 / 720p 每秒 40 / 1080p 每秒 80
+角色动画：480p 每秒 10 泥点，720p 每秒 20 泥点
+生成音效：10 泥点
+生成背景音乐：5 泥点
+```
+
+当前必须显式覆盖的正式模型定价配置：
+
+- 图片类：`gemini-3.1-flash-image-preview`（UI 显示与历史别名统一为 `nanobanana2`）为 12 泥点；`gpt-image-2` 为 20 泥点。
+- 规范：`gpt-image-2` 为 5 泥点。
+- 视频：`seedance2.0-fast` 为 10 / 20 泥点每秒；`seedance2.0` 为 12 / 24 泥点每秒；`kling3.0` 为 15 / 30 泥点每秒；`kling3.0-omni` 为 20 / 40 泥点每秒。兼容旧布局回放的 `veo3.1`、`veo3.1-fast` 也要保留 10 / 20 泥点每秒定价配置，但前端模型菜单不展示。
+- 角色动画：`seedance2.0-fast`。
+- 音效：`audio1.0`。
+- 背景音乐：`chirp-v5`。
+
+本次审计未发现当前正式入口缺少定价配置的模型；若后续新增模型，必须先补前端展示配置、前端提交计算、后端校验配置和对应测试，再出现在任一模型选择框中。
+
+## 生成视频模型与接口
+
+- 底部 `生成视频` 面板提交到 `POST /api/editor/videos/generations`。
+- 比例可选 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`；时长为 4 到 15 秒整数 slider；清晰度支持 `480p`、`720p`、`1080p`，但 `seedance2.0-fast` 不支持 `1080p`。静音为单个 toggle，默认有声；`webSearchEnabled` 默认提交为 `true` 但不在前端显示，后端当前不透传未知 Ark 字段。结果作为 `mediaType="video"`、`assetKind="video"` 的视频图层加入画布，并在画布中使用原生 `<video>` 播放控件渲染，不再走图片元素。
+- 支持模型：
+  - `seedance2.0-fast`
+  - `seedance2.0`
+  - `kling3.0`
+  - `kling3.0-omni`
+- 前端不展示 Veo 模型入口。
+- `seedance2.0-fast` 是生成视频默认项，并继续映射到 `doubao-seedance-2-0-fast-260128`；`seedance2.0` 是标准版可选项，必须独立映射到 `doubao-seedance-2-0-260128`，不得与 Fast 混用。
+- 角色动画生成固定使用 `seedance2.0-fast`，不继承生成视频标准版选择。
+- 后端复用现有 Ark / VectorEngine content generation task 轮询链路，并把生成视频持久化到 OSS；缺少 `ARK_CHARACTER_VIDEO_BASE_URL` 或 `ARK_CHARACTER_VIDEO_API_KEY` 时 fail-closed 返回配置错误。
+
+### Seedance 2.0 参考媒体与提交约束
+
+- 参考媒体只对 `seedance2.0-fast` / `seedance2.0` 开放；切换到 Kling 等非 Seedance 模型时，前端不提交 `referenceImageSrcs` / `referenceVideoSrcs` / `referenceAudioSrcs`，后端收到非 Seedance 参考字段必须拒绝。
+- 多模态参考按火山 Seedance 2.0 文档限制：参考图片 0~9 张，参考视频 0~3 个，参考音频 0~3 段；音频不可单独输入，必须至少搭配 1 张参考图片或 1 个参考视频。
+- 参考图片支持 URL / Base64 / `asset://` / 画板资源路径；格式为 jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30MB，请求体总大小不超过 64MB。
+- 参考视频只支持 URL / `asset://` / 画板资源路径，不支持 Base64 / `data:video/*`；格式为 mp4、mov，单个文件不超过 50MB，单个时长 [2, 15] 秒，最多 3 个且总时长不超过 15 秒。
+- 参考音频支持 URL / Base64 / `asset://` / 画板资源路径；格式为 wav、mp3，单个文件不超过 15MB，单个时长 [2, 15] 秒，最多 3 段且总时长不超过 15 秒。
+- 前端上传参考视频 / 参考音频必须走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 入库；前端状态保存 signed URL 供预览，同时保存 `objectKey` / `assetObjectId`，提交生成时优先使用 `objectKey`。
+- 后端接收画板资源 `objectKey` 后统一重新签名为 Ark 可读 URL，再按文档构造 `content`：`image_url` + `role=reference_image`、`video_url` + `role=reference_video`、`audio_url` + `role=reference_audio`。
+- 画板生成视频按静音 toggle 映射 Ark `generate_audio`：`sound=on` 时传 `true`，`sound=off` 时传 `false`，不能只依赖上游默认值。
+- Seedance 2.0 文档提示不支持直接上传含真人人脸的参考图 / 视频；当前画板尚未做真人脸授权证明、来源声明或服务端人脸拦截，后续开放真人素材前必须补授权/来源确认链路。
+
+## 验收
+
+- 所有生成类面板首行都是参考图区域。
+- 参考图槽位统一是方形图标；角色规范槽位显示规范 logo 和 `角色规范` 四字，悬停已有参考图时才显示右上角删除 `×`。
+- 比例 / 尺寸 / 模型不再平铺全部选项；比例与尺寸合并为左下角当前值按钮，模型与生成按钮位于右下角。
+- 单文本输入面板不显示字段标题，placeholder 是问题式文案。
+- 多文本输入面板字段标题和边界仍清晰；图标素材面板应只有一个 `素材描述` 文本输入框，不出现列表式 `素材描述 N` 卡片或添加描述按钮。
+- 生成按钮内能看到 `N泥点` 文案。
+- 弹出选项面板通过 `role=menu` 暴露，点击选项后保持打开，可连续修改多个字段。
+- 底边栏 `生成规范` / `生成音乐` 悬停即可看到上方选项面板；鼠标从按钮移动到选项面板时不闪退，离开按钮和选项面板后收起。
+- `生成音乐` 选项面板出现在音乐按钮上方，不再固定在底栏中间。
+- 规范面板比图片生成面板更紧凑，字段间距和输入高度更小，但外层 shell、首行参考图和底部按钮区必须继续对齐生成图片 / 生成角色 / 生成视频。
+- 生成规范类图片底部展示禁用态参数按钮 `16:9·2K` 和 `gpt-image-2`，视觉对齐可编辑面板的比例 / 尺寸 / 模型按钮；提交参数也固定为这三项，不出现可展开选项。
+- 快速编辑底部展示当前选择的比例 / 尺寸和模型，视觉对齐可编辑面板的比例 / 尺寸 / 模型按钮，并允许展开修改；额外参考图最多 8 张，原图作为隐式最后参考图参与提交但不在参考图条里固定显示 `图x`。
+- 快速编辑提交前必须把提示词里对原图的 `原图`、`当前图片`、`当前图` 或 `图1` 引用改写成最后一张原图编号，例如额外 1 张参考图时改为 `图2`。
+- 快速编辑提交给后端的参考图顺序必须是额外参考图在前、原图在最后。
+- 生成中的占位图聚焦后可用 `Delete` / `Backspace` 删除；删除后异步结果不再落回画布，也不显示额外删除 UI。
+- 快速编辑生成中的占位图同样只支持键盘 `Delete` / `Backspace` 删除，不新增 UI 删除按钮；删除后异步结果不得再落回画布。
+- 生成视频 / 角色形象 / 角色动作 / 音效 / 背景音乐新建后，画布占位空白样式和右上角标签均与对应生成类型一致，不再统一使用图片占位 icon。
+- 新建空白待生成占位的尺寸必须和面板参数一致；图片类修改比例 / 尺寸、视频修改清晰度后，画布空白占位同步变更且保持中心点。
+- 点击角色图只选中图层并显示工具栏，不自动弹出重绘、快速编辑或角色动画面板；点击工具栏或右键菜单中的 `生成动画` 才创建角色动作占位和面板。
+- 点击 UI 设计图只选中图层并显示工具栏；工具栏在 `去除背景按钮` 后显示 `提取素材`，点击后固定用 `gpt-image-2` 和提示词 `提取画面中的所有独立并整理成spritesheet` 生成 spritesheet，再复用图标素材拆分流程，把 spritesheet 图集和拆分素材都放到画布。
+- 生成游戏音效面板底部不显示字段标题，左下角只有一个时长参数按钮，选项为 Vidu duration `2-10` 秒；右下角固定模型胶囊显示 `Vidu` 并紧贴生成按钮。
+- 生成游戏背景音乐面板右下角固定模型胶囊显示 `Suno` 并紧贴生成按钮；`make_instrumental` 不在 UI 中展示。
+- 生成视频结果以视频图层加入画布，画布媒体元素标记为 `画布视频：生成视频 N`。
+- 生成器输入、参数、参考图和占位框在刷新后仍存在；已生成对象的生成器面板继续跟随成品图层。
+- Seedance 2.0 参考视频 / 音频上传不产生 `data:video/*` / 大体积音频 JSON；提交请求优先携带 `objectKey`，后端 Ark body 按 `sound` 映射 `generate_audio`，且不含未确认的 `mode` 字段。
diff --git a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
new file mode 100644
index 000000000..0d032d46d
--- /dev/null
+++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
@@ -0,0 +1,67 @@
+# 【编辑器】画板UI设计图生成入口设计
+
+日期：2026-06-17
+
+## 入口与画布状态
+
+- 底部 AI 画布工具栏新增 `生成UI设计图`。
+- 点击后立即在画布中新建 `UI设计图生成占位图`，不复用普通新建图片的空白样式。
+- 占位图默认 16:9 展示，生成成功后替换为 `assetKind: "ui-design"` 的画布图层。
+- 用户点击 `assetKind: "ui-design"` 图层后，图片上方浮动工具栏在 `去除背景按钮` 后显示 `提取素材` 按钮；普通图片、角色图和图标图层不显示该入口。
+
+## 生成面板
+
+- 占位图下方打开独立生成面板，标题为 `生成UI设计图`。
+- 面板复用普通 `生成图片` / `生成角色形象` / `生成视频` 的生成类 shell：首行参考图区域、中央单文本输入、底部参数与生成按钮区。
+- 面板第一个模块为 `图标规范`，并放在首行参考图区域。
+- 点击图标规范卡片后，在卡片旁弹出来源菜单：
+  - `从画布中选择`
+  - `新建图标规范`
+  - `上传图片`
+- `从画布中选择` 只接受 `assetKind: "icon-spec"` 的图层；普通图片、其他类别图层和不携带标签的图片不绑定。
+- `新建图标规范` 复用现有图标规范生成表单。
+- `上传图片` 仅绑定到当前 UI 设计面板的图标规范参考，不自动添加为画布图层。
+
+## 生成参数
+
+- 支持自定义画面比例和大小尺寸。
+- 模型固定为 `gpt-image-2`，面板不提供切换到其他模型的能力。
+- 默认画面比例为 `16:9`，默认大小为 `1K`。
+
+## 提示词契约
+
+后端收到 `kind: "ui-design"` 时固定拼接：
+
+```text
+生成玩法UI原型图
+【用户输入】<用户输入>
+```
+
+如果用户设置了图标规范参考图，则追加：
+
+```text
+参考图1为图标规范，请在UI图标、按钮符号、描边、材质、圆角、阴影和状态层级上严格遵循参考图1的素材规范。
+```
+
+生成请求固定使用 `gpt-image-2`。有参考图时走图片编辑请求；无参考图时走图片生成请求。
+
+## 提取素材
+
+- 点击浮动工具栏 `提取素材` 后，前端把当前 UI 设计图读取为图片 Data URL，提交到 `POST /api/editor/ui-designs/assets/extractions`。
+- 后端固定使用 `gpt-image-2` 图片编辑链路，并固定提示词：
+
+```text
+提取画面中的所有独立并整理成spritesheet
+```
+
+- 后端收到 spritesheet 后复用图标素材的连通域拆分能力；未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`。
+- 前端先把 spritesheet 原图作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分出的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布。
+
+## 验收点
+
+- 点击 `生成UI设计图` 后出现 UI 设计占位图和独立生成面板。
+- 面板第一模块为图标规范，来源菜单包含三个动作。
+- 从画布选择时只能绑定图标规范图片。
+- 请求参数包含 `kind: "ui-design"`、`model: "gpt-image-2"`、比例、大小与可选参考图。
+- 生成图层信息面板展示 `用户输入` 与 `图标规范`。
+- 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后调用固定 `gpt-image-2` 提取接口，画布同时出现 spritesheet 图集和拆分后的独立素材。
diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
new file mode 100644
index 000000000..9d43ebb96
--- /dev/null
+++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
@@ -0,0 +1,80 @@
+# 画板图标素材生成入口设计
+
+日期：`2026-06-15`
+
+## 背景
+
+图片画布编辑器已有普通图片生成、生成规范、生成角色形象和角色动画入口。本次新增 `生成图标素材`，用于一次输入多条图标素材描述，先生成一张绿幕 spritesheet，再自动去背、按连通域拆分为独立图标素材并铺到画布。
+
+## 入口与画布表现
+
+- 底部 AI 画布工具栏新增 `生成图标素材` 按钮。
+- 点击后立即在画布中心创建图标素材占位图，不复用普通“单张空白图片”图标；占位图表现为一叠空白素材图标卡片。
+- 图标素材面板锚定在占位图下方，和现有生成输入框同一层级展示。
+- 生成完成后删除占位态，先把后端返回的 spritesheet 原图作为 `assetKind: "icon-spritesheet"` 的图集图层放到画布，再把拆分出的每个独立图标素材作为画布图片图层铺开，图集与图标之间、图标彼此之间不重叠，并保留少量间距。
+- 图标素材图层写入 `assetKind: "icon"`；图标规范图写入 `assetKind: "icon-spec"`，用于刷新后保留标签和限制点选来源。
+
+## 面板结构
+
+1. 第一模块为 `图标规范`。
+   - 点击后弹出菜单：`从画布中选择`、`新建图标规范`、`上传图片`。
+   - `从画布中选择` 进入画布点选状态，只允许选择 `assetKind: "icon-spec"` 的图标规范图片；其它图片点击无效。
+   - `新建图标规范` 复用生成规范表单，规格类型为 `图标规范`，生成成功后图层标记为 `icon-spec`。
+   - `上传图片` 使用现有本地图片上传入口，上传图只绑定到本次面板，不自动放入画布。
+2. 第二模块为素材描述文本框。
+   - UI 复用角色形象生成面板同款单个文本输入框，让用户直接叙述多个素材。
+   - 默认按换行填入：`返回按钮`、`设置按钮`、`下一关按钮`、`提示按钮`、`原图按钮`、`冻结按钮`。
+   - 生成时按换行、逗号、顿号、分号、斜杠或竖线切分，过滤空文本后最多保留 `100` 个素材描述，并按文本顺序作为 prompt 的素材清单。
+
+## 面板外观
+
+- 图标素材面板不再使用列表式素材描述框，也不再按描述项横向扩宽；素材描述区改为与角色形象生成面板一致的单个文本输入框。
+- 图标规范入口采用 Lovart 式参考卡：左侧预览缩略图，中间显示当前绑定名称，右侧显示绑定状态和三个轻量动作入口，不再只是两行文字平铺。
+- 规范卡的 `从画布中选择 / 新建图标规范 / 上传图片` 继续保留独立菜单，但菜单只负责来源切换，不承载说明文案。
+
+## 生成契约
+
+- 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
+- 请求字段：
+  - `referenceImageSrc`：图标规范 Data URL。
+  - `iconDescriptions`：过滤空文本后的图标描述数组，`1..100`。
+  - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
+  - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
+  - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
+  - `priceMudPoints`：按当前模型从编辑器生成计费配置计算；`nanobanana2` 为 `12`，`gpt-image-2` 为 `20`。前端只提交配置函数计算值，后端用 `editor_generation_config` 校验，不允许素材生成面板自行写死价格。
+- 模型与尺寸选项：
+  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/edits`，把图标规范图作为 multipart `image`，按 `size` 映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+- 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
+- Prompt 固定为：
+
+```text
+参考图1的图标规范，单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景方便扣除背景，禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：
+
+<素材描述按中文顿号拼接>
+```
+
+## 去背与拆分
+
+- 后端收到 spritesheet 后先复用 `platform-image::generated_asset_sheets` 的绿幕去背能力。
+- 去背后基于 alpha 可见像素执行 8 邻域连通域检测。
+- 连通域按从上到下、从左到右排序；排序结果依次绑定面板中的素材描述名称。
+- 每个连通域裁剪时保留少量透明边距，并输出独立透明 PNG Data URL。
+- 若模型返回的连通域数量少于素材描述数量，接口返回失败，不在画布上铺半成品，避免名称和图标错位。
+
+## 前端铺放规则
+
+- spritesheet 图集放在原占位图左上附近。
+- 第一张拆分图标放在 spritesheet 图集右侧，后续图标按行铺开，图标之间保留约 `24px` 世界坐标间距。
+- 每个图标图层标题使用对应素材描述文本。
+- 生成成功后关闭图标素材面板，选中 spritesheet 图集，并打开图层面板。
+
+## 验收
+
+- 点击 `生成图标素材` 后出现一叠空白图标占位和图标素材面板。
+- `图标规范 -> 从画布中选择` 只能选择图标规范图，点击普通图片或角色规范图不会绑定。
+- 默认 6 个素材描述会进入 prompt；用户在单个文本框中继续输入时最多解析 100 个素材描述。
+- 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
+- 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
+- 生成成功后画布出现 spritesheet 图集和按描述命名的多个透明图标素材图层，图层之间不重叠。
+- 生成图标素材提交体包含按模型计算的 `priceMudPoints`；`nanobanana2` 应为 `12`，`gpt-image-2` 应为 `20`。若前端传入与后端计费配置不一致的值，后端返回 `priceMudPoints` 校验错误，不继续调用上游生成。
diff --git a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
new file mode 100644
index 000000000..fb37da587
--- /dev/null
+++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
@@ -0,0 +1,168 @@
+# 画板角色形象生成入口设计
+
+日期：`2026-06-15`
+
+## 背景
+
+图片画布编辑器已有普通图片生成与“生成规范”能力。本次新增“生成角色形象”入口，用于在同一画布内生成标注为“角色”的单张角色形象图片，并支持绑定角色规范与常规参考图。
+
+## 入口与画布表现
+
+- 底部 AI 画布工具栏新增 `生成角色形象` 按钮。
+- 点击后在画布中心创建一张空白图片占位图，面板锚定在占位图下方，视觉风格复用现有生成新图片面板；底部 AI 工具栏继续保持可见，不因角色面板打开而隐藏。
+- 占位图与生成成功后的图片右上角都覆盖 `角色` 标签。
+- 角色图层在布局快照中写入 `assetKind: "character"`，刷新后仍显示 `角色` 标签。
+
+## 面板结构
+
+角色生成面板只包含创作必需输入；每个输入框、参考图入口和选项按钮都必须展示对应中文字段标题，不只依赖 placeholder、按钮文案或 aria-label：
+
+1. 第一项参考图入口为 `角色规范`。
+   - 入口必须采用 Lovart 式参考图卡片：左侧小预览 / 图标，中间短标题，右侧仅保留必要状态，不把说明性规则文案铺在 UI 上。
+   - 点击后弹出菜单：`从画布中选择`、`新建角色规范`、`上传图片`。
+   - 来源菜单通过页面级 fixed portal 渲染，层级高于角色面板与参考图横向滚动区，不能被 `.image-canvas-editor__character-reference-row` 裁切。
+   - `从画布中选择` 进入画布点选状态，点击已有图片后把该图绑定为角色规范；按 `Esc` 退出点选状态。
+   - `新建角色规范` 复用当前 `生成规范 -> 角色规范` 流程。
+   - `上传图片` 使用现有本地图片上传入口。
+2. 规范入口后方是常规参考图入口。
+   - `上传常规参考图` 同样使用 Lovart 式参考图卡片，不只显示一段文字按钮。
+   - 上传后的每张常规参考图以缩略图展示。
+   - 每张常规参考图右下角显示大号序号，从 `1` 开始递增。
+3. 唯一文本框为 `角色设定`。
+4. 左下角展示画面比例和大小选择按钮。
+5. 右下角展示模型选择和生成按钮。
+
+## 普通生成面板视觉口径
+
+普通 `生成图片`、`生成角色形象`、`生成UI设计图` 等锚定在图片下方的生成面板统一采用 Lovart 式极简创作工具风格：
+
+- PC 端优先保持面板锚定在占位图或目标图片下方，宽度允许比旧版略宽，避免比例、尺寸、模型和生成按钮挤成一行难以阅读。
+- 面板只展示创作必需输入：参考图、提示词、比例、大小、模型和生成按钮；不在 UI 内铺说明性规则文案。
+- 视觉以白色半透明面板、轻边框、低阴影、低饱和选项按钮和清晰黑色主按钮为主，减少游戏式厚重装饰，贴近 Lovart 的极简画布工具感。
+- 普通 `生成图片` 面板的比例、大小和模型必须使用真实选项按钮，不再使用占位式参数按钮或弹出“建设中”提示。
+- 移动端仍可固定在底部工具栏上方并允许内部滚动，保证不遮挡底部 AI 工具栏和画布操作。
+
+## 生成与参考图契约
+
+- 前端提交角色生成时，使用 `POST /api/editor/images/generations`。
+- `kind` 传 `character`，用于后端日志 / 审计语义识别。
+- 角色规范与常规参考图作为 `referenceImageSrcs` 传入，顺序固定为：
+  1. 角色规范图。
+  2. 常规参考图列表。
+- 请求同时提交 `model`、`aspectRatio` 和 `imageSize`：
+  - `model` 支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
+  - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
+  - 比例按 `x:y` 展示；大小按 `0.5K / 1K / 2K` 展示。
+- 尺寸选项来源以 VectorEngine 接入文档为准：
+  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/generations` 或 `/v1/images/edits`，按文档尺寸映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+- 后端如果收到参考图，`nanobanana2` 把参考图作为 `inline_data` 传入原生 `generateContent`；`gpt-image-2` 走带多参考图的图片编辑链路。没有参考图时按所选模型走纯文本生成链路。
+- `kind = "character"` 时，后端不直接把前端文本当完整生图提示词，而是把文本作为 `角色设定` 填入固定提示词骨架：
+
+```text
+基于图1的角色美术视觉规范指导生成游戏角色形象图。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，禁止生成美术视觉规范、出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
+角色设定：<用户输入的角色设定>
+```
+
+- 角色图生成完成后，编辑器后端必须走通用抠图方法：复用 `platform-image::generated_asset_sheets` 的绿幕 / 近白背景去背能力，并开启内部绿幕 / 近白镂空检测。角色图 prompt 固定要求标准 `#00FF00 / RGB(0,255,0)` 绿幕；后端路径仍兼容生成模型把标准绿幕压成暗绿 / 灰绿背景的情况，但这类宽松识别只用于从画布边缘连通扩散出的背景，不作为全图断开绿色区域删除依据。该流程不再调用 RPG / 资产工坊的角色主图专用 `character_visual_assets` 后处理；输出仍统一为透明背景 PNG，随后写入 OSS 私有对象并确认 `asset_object`。接口回包仍返回透明 PNG Data URL 供画板立即显示，同时返回 `objectKey` / `assetObjectId`，前端创建图层和画板资源记录时必须保存这两个字段。
+- 对 `assetKind: "character"` 的角色图层执行 `重绘` 时，前端仍使用原图作为参考图，但请求 `kind` 必须传 `character`，让后端继续套用上述角色提示词限定、角色图后处理和角色资产持久化；普通图片图层重绘仍保持 `kind: "quick-edit"`。
+
+## 生成规范参考图
+
+- `生成规范 -> 角色规范`、`图标规范`、`图标规范`、`自定义规范` 的设定面板都支持上传 1 张参考图，并统一放在面板首行参考图区域。
+- 参考图入口只展示字段标题、缩略图或上传图标、文件名，不把参考规则说明铺在 UI 上。
+- 提交生成规范时，若存在参考图，前端必须把参考图作为 `referenceImageSrcs[0]` 提交到 `/api/editor/images/generations`，并在生图提示词开头自动追加“参考图生成规范”语义：要求模型参考图 1 的构图、风格、材质、色彩、形状语言和视觉层级生成规范图，但不要复制参考图中的文字、水印或无关背景。
+- 生成结果的信息快照必须记录该参考图，标题为 `参考图`，便于后续在图片信息面板回看生成输入。
+
+## 新建生成图落点避让
+
+- 普通生成、生成规范、生成角色形象和生成图标素材在创建画布占位图前，必须先检测占位图矩形是否与画布中已有可见图片图层或已有生成占位图重叠。
+- 若当前屏幕中心对应的画板位置可用，则占位图仍创建在该中心；若重叠，则以当前屏幕中心对应画板位置为原点，按距离由近到远查找不重叠候选位置。
+- 候选占位图与相邻图片或占位图之间保留 `32px` 画板间距；隐藏图层不阻挡新建落点。
+- 选中落点后保持当前缩放比例不变，将视口中心移动到新占位图中心，确保用户创建后立即看到新图和生成面板。
+
+## 图片信息展示
+
+- 图片信息弹窗标题固定为 `图片信息`，不拼接图片 / 图层名称。
+- 图片信息弹窗不展示 Provider 行，也不在 Task 中暴露 Provider 字符串。
+- Task 只展示任务标识里的数字部分；若任务标识没有数字，则显示 `-`。
+- 图片 / 图层名称只用于画布内部选择、图层列表和素材管理，不进入图片信息弹窗。
+
+## 可访问性与状态
+
+- 点选状态下画布显示状态提示 `请选择画布中的图片作为角色规范，按 Esc 退出`。
+- 已绑定的角色规范入口显示所选图片标题。
+- 生成中禁用参考图入口、文本框和按钮。
+- 点击画布空白区域让当前占位图或图片失焦时，关闭角色生成面板并移除图片选中样式；占位图本身保持可重新打开。删除图层逻辑沿用现有图层删除能力。
+
+## 验收
+
+- 点击 `生成角色形象` 后出现角色占位图、角色标签和角色生成面板。
+- 角色生成面板打开时底部 AI 工具栏仍可见；点击画布空白区域后面板关闭，当前图片不再显示选中边框。
+- `角色规范` 与 `上传常规参考图` 入口是带预览视觉块的参考图卡片，不是无样式文字。
+- `从画布中选择` 后点击已有画布图片可绑定为角色规范，`Esc` 可退出点选状态。
+- 上传常规参考图后缩略图右下角显示序号。
+- 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`aspectRatio` 和 `imageSize`。
+- 默认打开角色生成面板时选中 `nanobanana2 / 1:1 / 1K`；切换到 `gpt-image-2` 后再次打开角色或图标素材面板应沿用该模型。
+- 生成成功后在占位图位置创建 `assetKind: "character"` 图层，右上角显示 `角色` 标签，布局保存包含该字段。
+
+## 当前落地记录
+
+- 前端画板已接入 `生成角色形象` 底部入口、角色占位图、角色面板、画布点选规范图、上传规范图、上传常规参考图和序号角标。
+- 画布生成类入口已统一接入新建占位图落点避让：优先使用当前屏幕中心对应画板位置，重叠时自动选择最近的不重叠位置，并将视口中心移动到新占位图。
+- 角色生成提交统一走 `/api/editor/images/generations`，按 `角色规范 -> 常规参考图` 顺序传 `referenceImageSrcs`，并写入 `assetKind: "character"`。
+- 角色图层重绘同样走 `/api/editor/images/generations` 的 `kind: "character"` 分支，原图作为参考图提交，生成结果继续保留 `assetKind: "character"`。
+- 角色和图标素材生成已接入 `nanobanana2` / `gpt-image-2` 模型切换、上次模型记忆，以及按模型归一的比例 / 大小尺寸；`nanobanana2` 使用原生 `generateContent` 的 `imageConfig.aspectRatio/imageSize`，`gpt-image-2` 使用文档列出的 `size` 字符串。
+- 角色生成后端已按固定 prompt 骨架补入 `角色设定`，并在生成成功后通过编辑器通用抠图方法执行绿幕 / 近白背景去背和内部镂空清理、写入 `generated-character-drafts/editor/character-images/<taskId>/image.png` 路径下的 OSS 私有对象，返回的 `objectKey` / `assetObjectId` 会随画板资源记录保存。
+- `Esc` 只退出角色规范画布点选状态，不关闭角色生成面板。
+- 已补充回归测试覆盖角色形象生成、点选退出、角色动画入口隔离和快速编辑入口。
+- 本次验证命令：
+  - `npm test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`
+  - `npm test -- src/services/image-editor/editorProjectClient.test.ts`
+  - `npm run typecheck -- --pretty false`
+
+## 角色动画生成
+
+### 入口规则
+
+- 仅 `assetKind: "character"` 的角色图片图层显示 `生成动画` 入口。
+- 入口同时出现在图片上方悬浮工具条和图片右键功能列表中。
+- 非角色图片不得显示 `生成动画`，也不得通过右键菜单触发角色动画生成。
+- 点击 `生成动画` 后，在角色图片右侧打开独立的 `角色动画生成面板`；面板不在当前图片下方展开。
+
+### 面板字段
+
+1. 第一模块为 `动画描述` 文本框，最多输入 `4000` 字。
+2. 文本框下方提供预设动作提示词按钮：`待机`、`行走`、`奔跑`、`跳跃`、`攻击`、`受击`、`倒下`。点击后把对应动作文本写入动画描述文本框。
+3. 其它设置包括：
+   - 分辨率：`480p`、`720p`。
+   - 画面比例：默认 `与角色图片保持同尺寸`，可选 `1:1`、`4:3`、`16:9`、`9:16`、`3:4`。
+   - 时长：`32帧·4秒`、`40帧·5秒`、`48帧·6秒`。
+4. 模型固定使用 `seedance2.0-fast`，前端不提供模型切换。
+5. 生成按钮上方显示本次生成文本摘要和生成价格：
+   - `480p` 每秒 `10` 泥点。
+   - `720p` 每秒 `20` 泥点。
+
+### Prompt 与生成契约
+
+- 前端提交到 `POST /api/editor/character-animations/generations`。
+- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长。角色图片已经持久化到 OSS 时，`sourceImageSrc` 必须优先传 `objectKey`；只有未持久化的本地临时图片才允许传 Data URL。
+- 后端使用角色图片作为首帧和尾帧参考，模型固定映射到 `doubao-seedance-2-0-fast-260128`。
+- 后端路由兼容旧 Data URL 请求并单独放宽 JSON body limit 到 `12MB`，但该限额只作为兼容兜底，不作为新链路默认传大图的方式。
+- 后端 prompt 使用以下固定骨架，并把面板输入追加到 `动作描述：` 后：
+
+```text
+生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。
+动作描述：
+<用户输入的动画描述>
+```
+
+### 抽帧与 OSS 存储
+
+- 视频生成完成后，后端按面板选择抽取对应帧数：`32`、`40` 或 `48`。
+- 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。
+- 每帧必须执行绿幕去背，输出透明背景 PNG。
+- 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
+- 画板前端回填角色动作结果时，必须以 `previewVideoPath` 创建 `mediaType: "video"`、`assetKind: "character-animation"` 图层，复用视频素材的 `<video controls preload="metadata" playsInline>` 预览和视频下载 / 导出口径；不得把 `frames[0].imageSrc` 作为图层主 `src`。
+- `frames[0].imageSrc` 只作为动作视频图层的 `thumbnailSrc` / poster，以及后续动作素材快速编辑或再次生成动作时的透明帧来源。该规则不得跳过后端原有的视频生成、抽帧、绿幕去背和帧素材落盘流程。
+- 画板前端不把帧序列自动铺到画布上；后续若要展示逐帧图层，必须继续复用画布图层与素材库资源模型。
diff --git a/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md b/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md
new file mode 100644
index 000000000..5aa0221af
--- /dev/null
+++ b/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md
@@ -0,0 +1,134 @@
+# 画板音乐生成入口设计
+
+日期：`2026-06-18`
+
+## 范围
+
+本次只在 `/editor/canvas` 图片画布编辑器内新增底部 `生成音乐` 入口，用于生成完整游戏音效或游戏背景音乐。该入口属于画板生成类工具，不新增平台玩法入口、不进入作品发布链路，也不修改现有视觉小说音频生成开关。
+
+## 入口与交互
+
+1. 底部 AI 画布工具栏新增 `生成音乐`。
+2. 点击 `生成音乐` 后先弹出页面级 fixed 选项框，选项为：
+   - `生成游戏音效`
+   - `生成游戏背景音乐`
+3. 选择某一项后创建独立 `generation-dialog` 画布生成对象，并通过现有 placement 模型避让已有图层和占位。
+4. 面板 UI 复用 `生成角色形象` 的紧凑结构：上方为字段区，底部为参数 / 模型 / 生成按钮区，不写规则说明类文案。音效参数按钮靠左下角，固定模型胶囊紧贴生成按钮；背景音乐同样在右下角显示固定模型胶囊并紧贴生成按钮。
+5. 生成中隐藏设置面板，只保留画布中的音频生成占位；失败后恢复面板并展示短错误。
+
+## 面板字段
+
+### 生成游戏音效
+
+- `prompt`：用户输入的音效提示词。前端与 BFF 对内仍使用 `prompt`，提交到 VectorEngine Vidu 时同时写入 `prompt` 与 `sound` 同值，兼容线上网关对 `sound` 字段的反序列化要求。
+- `model`：固定默认 `audio1.0`，UI 以禁用态模型胶囊显示为 `Vidu`，位置紧贴生成按钮；暂不展示 Suno 文生音效模型入口。
+- `duration`：Vidu 音频时长，UI 以一个无标题参数按钮展示，选项范围 `2-10` 秒，默认 `5` 秒。
+- 提交到 VectorEngine 时映射为 Vidu 文生音频字段：`model: "audio1.0"`、`prompt`、`sound: prompt`、`duration`、可选 `seed`。当前编辑器音效固定使用 Vidu `audio1.0`，不再走 Suno `task: "sound"` / `metadata_params` 文生音效契约。
+
+### 生成游戏背景音乐
+
+- `gpt_description_prompt`：用户输入的背景音乐提示词。
+- `make_instrumental`：固定传 `true`，不在 UI 中展示为可改字段。
+- 提交到 VectorEngine 时映射为 Suno 纯音乐模式字段：`mv`、`gpt_description_prompt`、`make_instrumental: true`。`mv` 后端固定使用默认 Suno 模型，UI 以禁用态模型胶囊显示 `Suno`。
+- `gpt_description_prompt` 按 Apifox 契约限制 200 字，超出时由 BFF 返回参数错误。
+
+## 画布数据
+
+- 生成器继续保存到画布 layout JSON 的 `itemType: "generation-dialog"`，不新增表。
+- 新增生成器模式：
+  - `audio-sound-effect`
+  - `audio-background-music`
+- 新增结果图层媒体类型 `mediaType="audio"`。
+- 新增素材类型：
+  - `assetKind="sound-effect"`
+  - `assetKind="background-music"`
+- 音频结果以小型音频卡加入画布，卡片底部使用融入卡片的自定义播放器组件承载进度、时间和音量，播放 / 暂停只收口到卡片中央图标按钮；生成成功后同时保存为 OSS 私有对象、画布资源和账号级素材库素材，响应携带 `objectKey` / `assetObjectId` 供后续换签和复用。
+- 普通素材上传入口首版支持图片、MP3 和 MP4；MP3 / MP4 先走 OSS 直传和 asset object confirm，再以素材库素材保存，其他音视频格式暂不开放。
+- 音频结果卡片底部显示播放器辅助控件，不在卡片左下角或悬停左上角展示时长；提示词固定显示在卡片左上角。
+- 音频结果卡片底部播放器辅助控件仅在鼠标悬停音频卡片时从下方滑入显示，移出后向下滑出收起。
+- 音频卡片中央播放区按状态切换：未悬停且未播放时显示音效 / 背景音乐图标，悬停且未播放时显示播放按钮，播放中始终显示暂停按钮。
+- generated 私有音频资源播放前必须通过 `/api/assets/read-url` 换签；画布卡片不得直接把 `/generated-*` 或 generated OSS 私有地址交给 `<audio>` 裸请求。
+- 音频元数据弹窗使用 `时长`，不使用图片 / 视频的分辨率语义；音频生成占位不显示分辨率或时长角标。
+- 音频图层右上角标签显示在信息按钮左侧，和其他素材卡右上角信息区保持一致。
+- 元数据弹窗按音频显示 `音频信息` / `音频类型` / `时长`，生成输入快照只展示用户面板字段。
+- 音频图层上方浮动工具栏只保留 `改造` 和 `下载按钮`。点击 `改造` 后打开对应的音效或背景音乐生成面板，不展示参考图组件；面板底部模型与参数位置和原生成入口一致，并允许继续修改后再次生成，新结果落在原音频旁边。
+
+## 前端提交契约
+
+前端新增两个 BFF client：
+
+```ts
+POST /api/editor/audios/sound-effects/generations
+{
+  prompt: string,
+  model: "audio1.0",
+  duration: number,
+  priceMudPoints: 10
+}
+```
+
+```ts
+POST /api/editor/audios/background-music/generations
+{
+  gptDescriptionPrompt: string,
+  makeInstrumental: true,
+  priceMudPoints: 5
+}
+```
+
+统一响应：
+
+```ts
+{
+  ok: true,
+  audioSrc: string,
+  objectKey?: string | null,
+  assetObjectId?: string | null,
+  width: 420,
+  height: 120,
+  sourceType: "generated",
+  prompt: string,
+  actualPrompt?: string | null,
+  model: string,
+  provider: string,
+  taskId: string,
+  priceMudPoints: number,
+  audioKind: "sound-effect" | "background-music",
+  durationSeconds?: number | null
+}
+```
+
+## 后端实现
+
+- 在 `shared-contracts/src/assets.rs` 增加编辑器音频请求 / 响应 DTO。
+- 在 `platform-audio` 增加编辑器专用 body builder 和 submit 函数：
+  - 背景音乐 body 使用 `mv`、`gpt_description_prompt`、`make_instrumental`。
+  - Suno 音乐接口路径固定为 `/suno/submit/music`；`VECTOR_ENGINE_BASE_URL` 即使配置为带 `/v1` 的图片接口根，也要在 `platform-audio` 中归一为根路径后再拼接，避免误请求 `/v1/suno/submit/music`。
+  - 音效 body 使用 Vidu 文生音频契约：提交 `/ent/v2/text2audio`，请求体包含 `model: "audio1.0"`、`prompt`、`sound: prompt`、`duration` 和可选 `seed`；`model` 和 `prompt` 为文档必填，`sound` 用于兼容线上网关实际校验，`prompt` 最长 1500 字符，`duration` 按 Vidu 文档限制在 `2-10` 秒。
+  - 编辑器音效轮询使用 Vidu 路径 `/ent/v2/tasks/{taskId}/creations`，不再使用 Suno `/suno/fetch/{taskId}`；Suno 文生音效 `task: "sound"` 暂不从编辑器入口暴露。
+  - Suno 提交成功后的任务 ID 兼容与 wav clip 轮询逻辑只保留给背景音乐链路，避免误伤 `/api/editor/audios/background-music/generations`。
+  - VectorEngine 音频响应的 `code` 需要兼容 `"success"`、`"ok"`、`"0"`、`"200"` 以及数字 `0` / `200`；HTTP 非 2xx 时后端错误信息应透出安全的上游状态和短响应摘要，避免前端只显示笼统提交失败。
+- 在 `api-server` 增加编辑器音频 BFF：
+  - `/api/editor/audios/sound-effects/generations`
+  - `/api/editor/audios/background-music/generations`
+- BFF 复用现有 `vector_engine_audio_generation` 的任务轮询、下载、OSS 持久化和计费包装；音效 10 泥点，背景音乐 5 泥点。
+- 生成音频持久化后返回 OSS `objectKey` 与 `assetObjectId`；前端保存素材库时继续使用 `audioSrc` 作为兼容路径，并把 OSS 身份写入素材记录。
+
+## 验收
+
+- 底部工具栏显示 `生成音乐`。
+- 点击 `生成音乐` 只出现选项框，不立刻创建占位。
+- 点击 `生成游戏音效` 后出现音效面板，文本字段为 `prompt`；底部左侧只有一个无标题时长参数按钮，右侧为固定 `Vidu` 模型胶囊和生成按钮。
+- 音效时长只提供 `2-10` 秒选项，默认 `5` 秒，提交到 BFF 的字段为 `duration`。
+- 音效面板模型显示 `Vidu`，提交 `model: "audio1.0"`；后端转发到 Vidu 时同时携带 `prompt` 和 `sound`；不显示 Suno 文生音效模型或 Suno 音效入口。
+- 点击 `生成游戏背景音乐` 后出现背景音乐面板，字段为 `gpt_description_prompt`，右侧固定显示 `Suno` 模型胶囊，不展示 `make_instrumental`。
+- 音效提交到 `/api/editor/audios/sound-effects/generations`，背景音乐提交到 `/api/editor/audios/background-music/generations`。
+- 成功后画布新增音频卡，能通过卡片中央播放按钮播放，底部进度、时间和音量控件可操作。
+- 成功后音频素材自动出现在账号级素材库；从素材库再次添加到画布时仍恢复为 `mediaType="audio"` 音频图层。
+- 普通素材上传 MP3 / MP4 会写入 OSS 并进入素材库；MP3 添加到画布为音频图层，MP4 添加到画布为视频图层。
+- 成功后的音频卡展示提示词；卡片中央按未悬停图标、悬停播放、播放中暂停切换，不在底部重复显示播放 / 暂停按钮，播放器辅助控件直接融入卡片底部。
+- 鼠标未悬停音频卡时底部播放器辅助控件不可见，悬停时从底部滑动显现；提示词位于卡片左上角。
+- 音频卡片、悬停角标和待生成占位不显示时长；信息弹窗显示时长。
+- 音频素材浮动工具栏只显示 `改造` 与 `下载按钮`，`改造` 复用对应生成面板且没有参考图组件。
+- 私有 generated 音频能先换签再预览播放，不出现播放条一直为 `0:00` 的裸路径失败状态。
+- 刷新后 layout 能恢复音频生成器和音频图层。
diff --git a/output/playwright/editor-layout.png b/output/playwright/editor-layout.png
new file mode 100644
index 000000000..9ed5e24e1
Binary files /dev/null and b/output/playwright/editor-layout.png differ
diff --git a/output/playwright/editor-left-integrated-light.png b/output/playwright/editor-left-integrated-light.png
new file mode 100644
index 000000000..06fae79f9
Binary files /dev/null and b/output/playwright/editor-left-integrated-light.png differ
diff --git a/output/playwright/editor-lovart-panel-popup-final.png b/output/playwright/editor-lovart-panel-popup-final.png
new file mode 100644
index 000000000..dcf779797
Binary files /dev/null and b/output/playwright/editor-lovart-panel-popup-final.png differ
diff --git a/output/playwright/editor-no-outer-background.png b/output/playwright/editor-no-outer-background.png
new file mode 100644
index 000000000..9bc83c095
Binary files /dev/null and b/output/playwright/editor-no-outer-background.png differ
diff --git a/output/playwright/editor-plain-background.png b/output/playwright/editor-plain-background.png
new file mode 100644
index 000000000..2081e03c9
Binary files /dev/null and b/output/playwright/editor-plain-background.png differ
diff --git a/package-lock.json b/package-lock.json
index 528bddb54..9d5e617a0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,6 +12,7 @@
         "@vitejs/plugin-react": "^5.0.4",
         "cannon-es": "^0.20.0",
         "dotenv": "^17.2.3",
+        "jszip": "^3.10.1",
         "lucide-react": "^0.546.0",
         "motion": "^12.23.24",
         "qrcode": "^1.5.4",
@@ -2749,6 +2750,12 @@
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
       "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="
     },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
+      "license": "MIT"
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -3925,6 +3932,12 @@
         "node": ">= 4"
       }
     },
+    "node_modules/immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==",
+      "license": "MIT"
+    },
     "node_modules/import-fresh": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
@@ -3964,8 +3977,7 @@
     "node_modules/inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
-      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "dev": true
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
     },
     "node_modules/ini": {
       "version": "1.3.8",
@@ -4029,6 +4041,12 @@
       "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
       "dev": true
     },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
+      "license": "MIT"
+    },
     "node_modules/isexe": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -4203,6 +4221,48 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "license": "(MIT OR GPL-3.0-or-later)",
+      "dependencies": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      }
+    },
+    "node_modules/jszip/node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "license": "MIT",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/jszip/node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
+      "license": "MIT"
+    },
+    "node_modules/jszip/node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
     "node_modules/keyv": {
       "version": "4.5.4",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
@@ -4225,6 +4285,15 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "immediate": "~3.0.5"
+      }
+    },
     "node_modules/lightningcss": {
       "version": "1.32.0",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -4886,6 +4955,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "license": "(MIT AND Zlib)"
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -5114,6 +5189,12 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
+      "license": "MIT"
+    },
     "node_modules/psl": {
       "version": "1.15.0",
       "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz",
@@ -5463,6 +5544,12 @@
       "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
       "license": "ISC"
     },
+    "node_modules/setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==",
+      "license": "MIT"
+    },
     "node_modules/shebang-command": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -5996,9 +6083,7 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
       "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true
+      "license": "MIT"
     },
     "node_modules/v8-to-istanbul": {
       "version": "9.3.0",
@@ -9503,6 +9588,11 @@
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
       "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="
     },
+    "core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="
+    },
     "cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -10331,6 +10421,11 @@
       "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
       "dev": true
     },
+    "immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ=="
+    },
     "import-fresh": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
@@ -10360,8 +10455,7 @@
     "inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
-      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "dev": true
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
     },
     "ini": {
       "version": "1.3.8",
@@ -10408,6 +10502,11 @@
       "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
       "dev": true
     },
+    "isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="
+    },
     "isexe": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -10536,6 +10635,46 @@
       "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
       "dev": true
     },
+    "jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "requires": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      },
+      "dependencies": {
+        "readable-stream": {
+          "version": "2.3.8",
+          "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+          "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+          "requires": {
+            "core-util-is": "~1.0.0",
+            "inherits": "~2.0.3",
+            "isarray": "~1.0.0",
+            "process-nextick-args": "~2.0.0",
+            "safe-buffer": "~5.1.1",
+            "string_decoder": "~1.1.1",
+            "util-deprecate": "~1.0.1"
+          }
+        },
+        "safe-buffer": {
+          "version": "5.1.2",
+          "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+          "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
+        },
+        "string_decoder": {
+          "version": "1.1.1",
+          "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+          "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+          "requires": {
+            "safe-buffer": "~5.1.0"
+          }
+        }
+      }
+    },
     "keyv": {
       "version": "4.5.4",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
@@ -10555,6 +10694,14 @@
         "type-check": "~0.4.0"
       }
     },
+    "lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "requires": {
+        "immediate": "~3.0.5"
+      }
+    },
     "lightningcss": {
       "version": "1.32.0",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -10944,6 +11091,11 @@
       "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz",
       "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ=="
     },
+    "pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw=="
+    },
     "parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -11099,6 +11251,11 @@
         }
       }
     },
+    "process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="
+    },
     "psl": {
       "version": "1.15.0",
       "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz",
@@ -11334,6 +11491,11 @@
       "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
       "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw=="
     },
+    "setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA=="
+    },
     "shebang-command": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -11701,9 +11863,7 @@
     "util-deprecate": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
-      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "dev": true,
-      "optional": true
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="
     },
     "v8-to-istanbul": {
       "version": "9.3.0",
diff --git a/package.json b/package.json
index 537fa0846..fa497d129 100644
--- a/package.json
+++ b/package.json
@@ -109,6 +109,7 @@
     "@vitejs/plugin-react": "^5.0.4",
     "cannon-es": "^0.20.0",
     "dotenv": "^17.2.3",
+    "jszip": "^3.10.1",
     "lucide-react": "^0.546.0",
     "motion": "^12.23.24",
     "qrcode": "^1.5.4",
diff --git a/packages/shared/src/assets/chromaKey.test.ts b/packages/shared/src/assets/chromaKey.test.ts
new file mode 100644
index 000000000..125bb5393
--- /dev/null
+++ b/packages/shared/src/assets/chromaKey.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { removeBackgroundFromRgba } from './chromaKey';
+
+function createSolidRgbaBuffer({
+  width,
+  height,
+  color,
+}: {
+  width: number;
+  height: number;
+  color: [number, number, number, number];
+}) {
+  const pixels = new Uint8ClampedArray(width * height * 4);
+  for (let index = 0; index < width * height; index += 1) {
+    pixels.set(color, index * 4);
+  }
+  return pixels;
+}
+
+function setPixel(
+  pixels: Uint8ClampedArray,
+  width: number,
+  x: number,
+  y: number,
+  color: [number, number, number, number],
+) {
+  pixels.set(color, (y * width + x) * 4);
+}
+
+function alphaAt(
+  pixels: Uint8ClampedArray,
+  width: number,
+  x: number,
+  y: number,
+) {
+  return pixels[(y * width + x) * 4 + 3] ?? 0;
+}
+
+describe('chromaKey', () => {
+  it('removes near-white canvas background without breaking an enclosed white character', () => {
+    const width = 9;
+    const height = 9;
+    const pixels = createSolidRgbaBuffer({
+      width,
+      height,
+      color: [250, 250, 250, 255],
+    });
+
+    for (let y = 2; y <= 6; y += 1) {
+      for (let x = 2; x <= 6; x += 1) {
+        setPixel(pixels, width, x, y, [92, 80, 72, 255]);
+      }
+    }
+    for (let y = 3; y <= 5; y += 1) {
+      for (let x = 3; x <= 5; x += 1) {
+        setPixel(pixels, width, x, y, [246, 246, 244, 255]);
+      }
+    }
+
+    expect(removeBackgroundFromRgba(pixels, width, height)).toBe(true);
+
+    expect(alphaAt(pixels, width, 0, 0)).toBe(0);
+    expect(alphaAt(pixels, width, 4, 4)).toBe(255);
+    expect(alphaAt(pixels, width, 2, 2)).toBeGreaterThan(200);
+  });
+});
diff --git a/packages/shared/src/contracts/runtime.ts b/packages/shared/src/contracts/runtime.ts
index b0d5c74ca..3e76215b4 100644
--- a/packages/shared/src/contracts/runtime.ts
+++ b/packages/shared/src/contracts/runtime.ts
@@ -75,6 +75,30 @@ export type ProfileWalletLedgerResponse = {
   entries: ProfileWalletLedgerEntry[];
 };
 
+export type ExternalApiKeyProfile = {
+  keyId: string;
+  name: string;
+  keyPrefix: string;
+  scopes: string[];
+  createdAt: string;
+  lastUsedAt: string | null;
+  revokedAt: string | null;
+  updatedAt: string;
+};
+
+export type ExternalApiKeyListResponse = {
+  keys: ExternalApiKeyProfile[];
+};
+
+export type ExternalApiKeyCreateResponse = {
+  apiKey: string;
+  key: ExternalApiKeyProfile;
+};
+
+export type ExternalApiKeyMutationResponse = {
+  key: ExternalApiKeyProfile;
+};
+
 export type ProfileRechargeProductKind = 'points' | 'membership';
 export type ProfileMembershipStatus = 'normal' | 'active';
 export type ProfileMembershipTier = 'normal' | 'month' | 'season' | 'year';
diff --git a/packages/shared/src/prompts/qwenSprite.ts b/packages/shared/src/prompts/qwenSprite.ts
index 68b5ff832..560a22b45 100644
--- a/packages/shared/src/prompts/qwenSprite.ts
+++ b/packages/shared/src/prompts/qwenSprite.ts
@@ -134,7 +134,7 @@ export function buildMasterPrompt(characterBrief: string) {
     '单人，2D 横版游戏角色标准设定图，主体完整可见，底部轮廓完整，身体比例稳定，轮廓清楚，适合后续制作 sprite sheet 动画。',
     `视角要求：角色采用横版动作素材常用的右向斜侧身站姿，身体整体朝右，但保留少量正面信息，能读到面部轮廓与胸肩结构，不是完全 90 度纯右视图，也不是正面立绘。`,
     `主体要求：画面中只保留单个角色主体，不要额外人物、动物、召唤物、载具或陪体。`,
-    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为纯绿色绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
+    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
     `风格要求：${BODY_RATIO_TEXT} ${PIXEL_STYLE_TEXT} 高可读性游戏角色设定图，形体清晰，服装层次明确，优先体现像素动作角色感而不是软萌 Q版插画感，便于后续连续动作生成。`,
     '请先拆解设定中的“身份词、主题词、身体结构词”。如果文字设定没有明确要求非人身体结构，默认优先使用参考图对应的人类或类人动作角色骨架，保持清楚的头、躯干、手臂和双腿轮廓，只有当文字设定明确要求非人结构时，才改为对应非人身体。',
     '主题词默认只作用在角色自身的服装剪裁、材质、纹样、饰品、发光细节上，不要把主题词自动扩写成背景建筑、自然场景、漂浮装饰或额外环境物件。',
@@ -163,11 +163,11 @@ export function buildVideoActionPrompt(options: {
     `角色固定为图1同一角色，保持右向斜侧身动作视角，镜头稳定，轮廓清晰，不要退化成完全 90 度纯右视图。`,
     `视角要求：角色采用横版动作素材常用的右向斜侧身站姿，身体整体朝右，但保留少量正面信息，能读到面部轮廓与胸肩结构，不是完全 90 度纯右视图，也不是正面立绘。`,
     `主体要求：画面中只保留单个角色主体，不要额外人物、动物、召唤物、载具或陪体。`,
-    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为纯绿色绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
+    `画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素或其他角色以外的场景内容。`,
     `风格要求：${BODY_RATIO_TEXT} ${PIXEL_STYLE_TEXT} 高可读性游戏角色设定图，偏像素动画前置设计稿，形体清晰，服装层次明确，道具/权杖/武器如有则存在关系合理，优先保证像素动作角色感，不要退化成只剩 Q 版比例的普通插画，便于后续连续动作生成。`,
     `动作结构：${options.actionTemplate.sequenceLines.join('；')}。结尾要求：${options.actionTemplate.ending}。`,
     options.useChromaKey
-      ? '背景为纯绿色绿幕，无其他人物和场景元素，方便后期抽帧与抠像。'
+      ? '背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素，方便后期抽帧与抠像。'
       : '背景简洁纯净，无复杂场景。',
     `动作补充细节：${options.actionDetailText.trim() || '保持动作清晰、节奏明确、适合后续抽帧为 sprite sheet。'}`,
     `角色设定：${options.characterBrief.trim()}`,
diff --git a/public/creation-home/asset-manifest.json b/public/creation-home/asset-manifest.json
new file mode 100644
index 000000000..566b5fb3d
--- /dev/null
+++ b/public/creation-home/asset-manifest.json
@@ -0,0 +1,117 @@
+{
+  "generatedBy": "VectorEngine gpt-image-2",
+  "generatedFor": "/creation 创作工具主页 image2 风格资源",
+  "styleReference": "用户提供参考图 codex-clipboard-5ee77a57-5ceb-46c7-a309-f6c8e374d989.png",
+  "constraints": [
+    "无图内文字",
+    "不替换现有 UI 文案",
+    "只作为视觉资源接入"
+  ],
+  "assets": [
+    {
+      "file": "/creation-home/background-clay-workspace.png",
+      "subject": "暖白陶泥纸感工作台背景纹理",
+      "bytes": 1253141
+    },
+    {
+      "file": "/creation-home/brand-mascot.png",
+      "subject": "陶泥儿品牌小陶偶头像",
+      "bytes": 265352
+    },
+    {
+      "file": "/creation-home/feature-character.png",
+      "subject": "游戏角色",
+      "bytes": 257922
+    },
+    {
+      "file": "/creation-home/feature-coding.png",
+      "subject": "游戏功能编码",
+      "bytes": 280325
+    },
+    {
+      "file": "/creation-home/feature-effects.png",
+      "subject": "游戏特效",
+      "bytes": 246466
+    },
+    {
+      "file": "/creation-home/feature-export.png",
+      "subject": "一键导出",
+      "bytes": 230725
+    },
+    {
+      "file": "/creation-home/feature-marketing.png",
+      "subject": "游戏美宣",
+      "bytes": 272968
+    },
+    {
+      "file": "/creation-home/feature-music.png",
+      "subject": "游戏音乐",
+      "bytes": 258027
+    },
+    {
+      "file": "/creation-home/feature-scene.png",
+      "subject": "游戏场景",
+      "bytes": 284949
+    },
+    {
+      "file": "/creation-home/feature-ui.png",
+      "subject": "游戏 UI",
+      "bytes": 280537
+    },
+    {
+      "file": "/creation-home/feature-visual-spec.png",
+      "subject": "游戏视觉规范",
+      "bytes": 297305
+    },
+    {
+      "file": "/creation-home/hero-community.png",
+      "subject": "玩家社区按钮图标",
+      "bytes": 250131
+    },
+    {
+      "file": "/creation-home/hero-create.png",
+      "subject": "开始创作按钮图标",
+      "bytes": 242745
+    },
+    {
+      "file": "/creation-home/nav-create.png",
+      "subject": "左侧导航创作",
+      "bytes": 278377
+    },
+    {
+      "file": "/creation-home/nav-discover.png",
+      "subject": "左侧导航发现",
+      "bytes": 261177
+    },
+    {
+      "file": "/creation-home/nav-profile.png",
+      "subject": "左侧导航我的",
+      "bytes": 288027
+    },
+    {
+      "file": "/creation-home/nav-projects.png",
+      "subject": "左侧导航项目 / 草稿兜底",
+      "bytes": 247891
+    },
+    {
+      "file": "/creation-home/nav-recommend.png",
+      "subject": "左侧导航推荐",
+      "bytes": 284543
+    },
+    {
+      "file": "/creation-home/project-new.png",
+      "subject": "新建项目",
+      "bytes": 260908
+    },
+    {
+      "file": "/creation-home/topbar-search.png",
+      "subject": "顶部搜索",
+      "bytes": 241211
+    },
+    {
+      "file": "/creation-home/topbar-wallet.png",
+      "subject": "顶部泥点余额",
+      "bytes": 280555
+    }
+  ]
+}
\ No newline at end of file
diff --git a/public/creation-home/background-clay-workspace.png b/public/creation-home/background-clay-workspace.png
new file mode 100644
index 000000000..c32e5c1fc
Binary files /dev/null and b/public/creation-home/background-clay-workspace.png differ
diff --git a/public/creation-home/brand-mascot.png b/public/creation-home/brand-mascot.png
new file mode 100644
index 000000000..8574c8c19
Binary files /dev/null and b/public/creation-home/brand-mascot.png differ
diff --git a/public/creation-home/feature-character.png b/public/creation-home/feature-character.png
new file mode 100644
index 000000000..24e1c25d6
Binary files /dev/null and b/public/creation-home/feature-character.png differ
diff --git a/public/creation-home/feature-coding.png b/public/creation-home/feature-coding.png
new file mode 100644
index 000000000..5ea677d09
Binary files /dev/null and b/public/creation-home/feature-coding.png differ
diff --git a/public/creation-home/feature-effects.png b/public/creation-home/feature-effects.png
new file mode 100644
index 000000000..113f5155c
Binary files /dev/null and b/public/creation-home/feature-effects.png differ
diff --git a/public/creation-home/feature-export.png b/public/creation-home/feature-export.png
new file mode 100644
index 000000000..34714030e
Binary files /dev/null and b/public/creation-home/feature-export.png differ
diff --git a/public/creation-home/feature-marketing.png b/public/creation-home/feature-marketing.png
new file mode 100644
index 000000000..81bd39d88
Binary files /dev/null and b/public/creation-home/feature-marketing.png differ
diff --git a/public/creation-home/feature-music.png b/public/creation-home/feature-music.png
new file mode 100644
index 000000000..8d47e6e2e
Binary files /dev/null and b/public/creation-home/feature-music.png differ
diff --git a/public/creation-home/feature-scene.png b/public/creation-home/feature-scene.png
new file mode 100644
index 000000000..d86023c32
Binary files /dev/null and b/public/creation-home/feature-scene.png differ
diff --git a/public/creation-home/feature-ui.png b/public/creation-home/feature-ui.png
new file mode 100644
index 000000000..84c726478
Binary files /dev/null and b/public/creation-home/feature-ui.png differ
diff --git a/public/creation-home/feature-visual-spec.png b/public/creation-home/feature-visual-spec.png
new file mode 100644
index 000000000..a71881f54
Binary files /dev/null and b/public/creation-home/feature-visual-spec.png differ
diff --git a/public/creation-home/hero-community.png b/public/creation-home/hero-community.png
new file mode 100644
index 000000000..85abf0b1a
Binary files /dev/null and b/public/creation-home/hero-community.png differ
diff --git a/public/creation-home/hero-create.png b/public/creation-home/hero-create.png
new file mode 100644
index 000000000..1da8dc65e
Binary files /dev/null and b/public/creation-home/hero-create.png differ
diff --git a/public/creation-home/nav-create.png b/public/creation-home/nav-create.png
new file mode 100644
index 000000000..b3efa6fd9
Binary files /dev/null and b/public/creation-home/nav-create.png differ
diff --git a/public/creation-home/nav-discover.png b/public/creation-home/nav-discover.png
new file mode 100644
index 000000000..82a6cdf6f
Binary files /dev/null and b/public/creation-home/nav-discover.png differ
diff --git a/public/creation-home/nav-profile.png b/public/creation-home/nav-profile.png
new file mode 100644
index 000000000..298247085
Binary files /dev/null and b/public/creation-home/nav-profile.png differ
diff --git a/public/creation-home/nav-projects.png b/public/creation-home/nav-projects.png
new file mode 100644
index 000000000..d822aece6
Binary files /dev/null and b/public/creation-home/nav-projects.png differ
diff --git a/public/creation-home/nav-recommend.png b/public/creation-home/nav-recommend.png
new file mode 100644
index 000000000..4e97197bf
Binary files /dev/null and b/public/creation-home/nav-recommend.png differ
diff --git a/public/creation-home/project-new.png b/public/creation-home/project-new.png
new file mode 100644
index 000000000..14d2172d8
Binary files /dev/null and b/public/creation-home/project-new.png differ
diff --git a/public/creation-home/topbar-search.png b/public/creation-home/topbar-search.png
new file mode 100644
index 000000000..e871fe965
Binary files /dev/null and b/public/creation-home/topbar-search.png differ
diff --git a/public/creation-home/topbar-wallet.png b/public/creation-home/topbar-wallet.png
new file mode 100644
index 000000000..5a9177010
Binary files /dev/null and b/public/creation-home/topbar-wallet.png differ
diff --git a/public/match3d-background-references/pot-fused-reference-candidate-v2.prompt.txt b/public/match3d-background-references/pot-fused-reference-candidate-v2.prompt.txt
index f6e2cd4fb..2e610fc4d 100644
--- a/public/match3d-background-references/pot-fused-reference-candidate-v2.prompt.txt
+++ b/public/match3d-background-references/pot-fused-reference-candidate-v2.prompt.txt
@@ -1 +1 @@
-生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只生成一个完整容器，画面中绝对不能出现第二个容器、备选方案、上下排列、多个版本或任何物品。参考用户给出的木质圆形容器图片的外边缘面积和视角：容器外轮廓接近画布四边，宽度约占画布 88%-92%，高度约占画布 84%-90%，主体中心略偏下；只留很少外侧空间。容器类型：游戏 UI 用的圆形浅盘/浅碗竞技容器，外圈厚实，前沿较高且可见，后沿也能看到层次；整体像一只浅而宽的木质或竹编圆形容器，而不是深锅。视角：轻俯视 3/4 上方视角，必须能看到容器外壁、厚实前沿、内壁层次和横向椭圆形内口；不能画成正俯视扁圆盘、不能画成侧视碗、不能画成小托盘。内部必须是干净空的浅盘空间：只有平滑的金色木质或竹质内底和内壁层次，不要内部图案、不要发光球、不要食物、不要水、不要场景、不要物品槽、不要棋盘。风格：高品质休闲游戏 2D UI 资产，清晰轮廓，柔和体积光影，边缘干净，可作为抓大鹅运行态中心棋盘覆盖层。背景必须是完全平整统一的纯绿色 #00FF00 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。禁止文字、水印、按钮、倒计时、分数、HUD、教程浮层、菜单、角色、手、动物、logo、边框、网格线。
\ No newline at end of file
+生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只生成一个完整容器，画面中绝对不能出现第二个容器、备选方案、上下排列、多个版本或任何物品。参考用户给出的木质圆形容器图片的外边缘面积和视角：容器外轮廓接近画布四边，宽度约占画布 88%-92%，高度约占画布 84%-90%，主体中心略偏下；只留很少外侧空间。容器类型：游戏 UI 用的圆形浅盘/浅碗竞技容器，外圈厚实，前沿较高且可见，后沿也能看到层次；整体像一只浅而宽的木质或竹编圆形容器，而不是深锅。视角：轻俯视 3/4 上方视角，必须能看到容器外壁、厚实前沿、内壁层次和横向椭圆形内口；不能画成正俯视扁圆盘、不能画成侧视碗、不能画成小托盘。内部必须是干净空的浅盘空间：只有平滑的金色木质或竹质内底和内壁层次，不要内部图案、不要发光球、不要食物、不要水、不要场景、不要物品槽、不要棋盘。风格：高品质休闲游戏 2D UI 资产，清晰轮廓，柔和体积光影，边缘干净，可作为抓大鹅运行态中心棋盘覆盖层。背景必须是完全平整统一的纯绿色 #00FF00 / RGB(0,255,0) 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。禁止文字、水印、按钮、倒计时、分数、HUD、教程浮层、菜单、角色、手、动物、logo、边框、网格线。
\ No newline at end of file
diff --git a/public/match3d-background-references/pot-fused-reference-candidate-v3.prompt.txt b/public/match3d-background-references/pot-fused-reference-candidate-v3.prompt.txt
index dc0a0737e..f8f6d7423 100644
--- a/public/match3d-background-references/pot-fused-reference-candidate-v3.prompt.txt
+++ b/public/match3d-background-references/pot-fused-reference-candidate-v3.prompt.txt
@@ -1 +1 @@
-生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只生成一个完整容器，不能出现第二个容器、多个方案、物品、角色、手、文字或任何 UI 控件。视图必须严格贴近用户红线标注的容器视角：正前方轻俯视，不要明显左右 3/4 偏转；容器外轮廓接近圆形大桶，主体宽度占画布 94%-98%，高度占画布 92%-98%，几乎顶到画布四边。开口面积必须很大：上方开口是一个巨大的横向椭圆，外开口椭圆宽度占容器外宽的 90%-94%，开口椭圆高度占容器外高的 62%-70%；开口上缘靠近画布顶部，开口下缘要落到画布垂直方向约 66%-72% 的位置。容器不是浅盘。必须是有明显深度的圆形木桶/竹桶式竞技容器：后壁高，左右内壁厚，前壁从开口下缘到容器底部有明显高度，能看到厚实前沿和外壁纵深。内部空间必须干净可放 2D 物品：只保留平滑的金色木质内底、内壁层次和柔和阴影；不要内部图案、不要发光球、不要食物、不要水、不要格子、不要物品槽、不要棋盘。外沿和内沿要像红线圈出的结构：大而连续的圆桶边缘，前沿厚实，后沿在顶部形成弧形，内部底面是低处的横向椭圆平面。风格：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，适合覆盖在移动端抓大鹅中心棋盘。背景必须是完全平整统一的纯绿色 #00FF00 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：浅盘、小托盘、扁圆盘、低矮盘子、侧视碗、斜向 3/4 侧视、上下两个容器、多个版本、开口太小、开口太扁、画布大量留白、红线、标注线、文字、水印、logo。
\ No newline at end of file
+生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只生成一个完整容器，不能出现第二个容器、多个方案、物品、角色、手、文字或任何 UI 控件。视图必须严格贴近用户红线标注的容器视角：正前方轻俯视，不要明显左右 3/4 偏转；容器外轮廓接近圆形大桶，主体宽度占画布 94%-98%，高度占画布 92%-98%，几乎顶到画布四边。开口面积必须很大：上方开口是一个巨大的横向椭圆，外开口椭圆宽度占容器外宽的 90%-94%，开口椭圆高度占容器外高的 62%-70%；开口上缘靠近画布顶部，开口下缘要落到画布垂直方向约 66%-72% 的位置。容器不是浅盘。必须是有明显深度的圆形木桶/竹桶式竞技容器：后壁高，左右内壁厚，前壁从开口下缘到容器底部有明显高度，能看到厚实前沿和外壁纵深。内部空间必须干净可放 2D 物品：只保留平滑的金色木质内底、内壁层次和柔和阴影；不要内部图案、不要发光球、不要食物、不要水、不要格子、不要物品槽、不要棋盘。外沿和内沿要像红线圈出的结构：大而连续的圆桶边缘，前沿厚实，后沿在顶部形成弧形，内部底面是低处的横向椭圆平面。风格：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，适合覆盖在移动端抓大鹅中心棋盘。背景必须是完全平整统一的纯绿色 #00FF00 / RGB(0,255,0) 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：浅盘、小托盘、扁圆盘、低矮盘子、侧视碗、斜向 3/4 侧视、上下两个容器、多个版本、开口太小、开口太扁、画布大量留白、红线、标注线、文字、水印、logo。
\ No newline at end of file
diff --git a/public/match3d-background-references/pot-fused-reference-candidate-v4.prompt.txt b/public/match3d-background-references/pot-fused-reference-candidate-v4.prompt.txt
index 9c1be0ce9..9fa2f5ce5 100644
--- a/public/match3d-background-references/pot-fused-reference-candidate-v4.prompt.txt
+++ b/public/match3d-background-references/pot-fused-reference-candidate-v4.prompt.txt
@@ -1 +1 @@
-生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只允许一个完整容器。不要多个容器、不要备选方案、不要物品、不要角色、不要手、不要文字、不要红色标注线。视图必须贴近用户红线标注：正前方轻俯视的圆形木桶容器，yaw=0，不要左右偏转，不要斜向 3/4 侧视。外轮廓要几乎撑满画布：左边缘在 x=0-25，右边缘在 x=999-1024，顶部外沿在 y=35-70，底部桶身在 y=980-1024；画布上方和左右只留极少白边。开口面积和角度是核心：顶部开口是一个巨大的横向椭圆，外开口椭圆宽度约为画布 94%-98%，高度约为画布 72%-80%，椭圆上缘在 y=50-85，椭圆下缘在 y=790-850。容器必须是连续闭合的圆桶/竹桶，不是浅盘。前沿不能出现缺口、断口、凹口、门洞或围栏式开口；前方桶壁必须连续完整，从开口下缘一直延伸到画布底部附近。桶壁要有明显厚度和深度：后壁高、左右内壁厚、前壁厚实，能看到内壁层次、顶部厚外沿、内侧圆弧和下方桶身外壁。内部必须空且干净：只有金色木质内底和柔和阴影，底面是低处的横向椭圆平面；不要发光球、不要食物、不要水、不要纹章、不要格子、不要棋盘、不要物品槽。造型接近用户参考图外边缘：圆润木桶外形，厚实金色木质外沿，大开口，大前壁，整体像可以承载大量 2D 物品的中心竞技容器。风格：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，边缘干净。背景必须完全平整统一纯绿色 #00FF00 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：浅盘、小托盘、低矮盘子、正俯视扁圆盘、侧视碗、左右斜视、前沿缺口、围栏缺口、画布大量留白、内部图案、红线、文字、水印、logo。
\ No newline at end of file
+生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只允许一个完整容器。不要多个容器、不要备选方案、不要物品、不要角色、不要手、不要文字、不要红色标注线。视图必须贴近用户红线标注：正前方轻俯视的圆形木桶容器，yaw=0，不要左右偏转，不要斜向 3/4 侧视。外轮廓要几乎撑满画布：左边缘在 x=0-25，右边缘在 x=999-1024，顶部外沿在 y=35-70，底部桶身在 y=980-1024；画布上方和左右只留极少白边。开口面积和角度是核心：顶部开口是一个巨大的横向椭圆，外开口椭圆宽度约为画布 94%-98%，高度约为画布 72%-80%，椭圆上缘在 y=50-85，椭圆下缘在 y=790-850。容器必须是连续闭合的圆桶/竹桶，不是浅盘。前沿不能出现缺口、断口、凹口、门洞或围栏式开口；前方桶壁必须连续完整，从开口下缘一直延伸到画布底部附近。桶壁要有明显厚度和深度：后壁高、左右内壁厚、前壁厚实，能看到内壁层次、顶部厚外沿、内侧圆弧和下方桶身外壁。内部必须空且干净：只有金色木质内底和柔和阴影，底面是低处的横向椭圆平面；不要发光球、不要食物、不要水、不要纹章、不要格子、不要棋盘、不要物品槽。造型接近用户参考图外边缘：圆润木桶外形，厚实金色木质外沿，大开口，大前壁，整体像可以承载大量 2D 物品的中心竞技容器。风格：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，边缘干净。背景必须完全平整统一纯绿色 #00FF00 / RGB(0,255,0) 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：浅盘、小托盘、低矮盘子、正俯视扁圆盘、侧视碗、左右斜视、前沿缺口、围栏缺口、画布大量留白、内部图案、红线、文字、水印、logo。
\ No newline at end of file
diff --git a/public/match3d-background-references/pot-fused-reference-candidate-v5.prompt.txt b/public/match3d-background-references/pot-fused-reference-candidate-v5.prompt.txt
index 9bb2e00a7..cc42ec01a 100644
--- a/public/match3d-background-references/pot-fused-reference-candidate-v5.prompt.txt
+++ b/public/match3d-background-references/pot-fused-reference-candidate-v5.prompt.txt
@@ -1 +1 @@
-生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只允许一个完整容器。不要多个容器、不要备选方案、不要物品、不要角色、不要手、不要文字、不要红色标注线。核心比例：开口是绝对主体，桶身只是装饰。可见桶身高度必须只有开口椭圆高度的约 1/8（12.5%），不要高桶身，不要深桶。开口必须极大：正前方轻俯视的巨大横向椭圆开口，外开口椭圆宽度占画布 94%-98%，开口椭圆高度占画布 78%-84%。开口上缘接近 y=45，开口下缘接近 y=850。桶身必须极矮：从前沿下缘到容器底部只保留一圈薄木质装饰桶身，高度约 90-110 像素；底部接近 y=960-990。整体看起来像一个超大开口的低矮木质竞技圈，不像深木桶。前方装饰边必须连续闭合，没有缺口、门洞或围栏断口。前沿是一圈厚实圆润的木质环，桶身只是这圈环下面的一小段装饰外壁。内部必须空且干净：只有平滑金色木质内底、内壁圆弧和柔和阴影；不要发光、不要食物、不要水、不要纹章、不要格子、不要棋盘、不要物品槽。视角：正前方轻俯视，yaw=0，不要左右斜向 3/4 侧视。能看到超大开口内部和很矮的前方外壁。造型：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，边缘干净，适合覆盖在移动端抓大鹅中心棋盘。背景必须完全平整统一纯绿色 #00FF00 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：高桶身、深锅、深木桶、桶身高度超过开口高度 1/6、浅盘、小托盘、低矮盘子、正俯视扁圆盘、侧视碗、左右斜视、前沿缺口、画布大量留白、内部图案、红线、文字、水印、logo。
\ No newline at end of file
+生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。只允许一个完整容器。不要多个容器、不要备选方案、不要物品、不要角色、不要手、不要文字、不要红色标注线。核心比例：开口是绝对主体，桶身只是装饰。可见桶身高度必须只有开口椭圆高度的约 1/8（12.5%），不要高桶身，不要深桶。开口必须极大：正前方轻俯视的巨大横向椭圆开口，外开口椭圆宽度占画布 94%-98%，开口椭圆高度占画布 78%-84%。开口上缘接近 y=45，开口下缘接近 y=850。桶身必须极矮：从前沿下缘到容器底部只保留一圈薄木质装饰桶身，高度约 90-110 像素；底部接近 y=960-990。整体看起来像一个超大开口的低矮木质竞技圈，不像深木桶。前方装饰边必须连续闭合，没有缺口、门洞或围栏断口。前沿是一圈厚实圆润的木质环，桶身只是这圈环下面的一小段装饰外壁。内部必须空且干净：只有平滑金色木质内底、内壁圆弧和柔和阴影；不要发光、不要食物、不要水、不要纹章、不要格子、不要棋盘、不要物品槽。视角：正前方轻俯视，yaw=0，不要左右斜向 3/4 侧视。能看到超大开口内部和很矮的前方外壁。造型：高品质休闲游戏 2D UI 资产，暖金木质或竹质，清晰轮廓，柔和体积光影，边缘干净，适合覆盖在移动端抓大鹅中心棋盘。背景必须完全平整统一纯绿色 #00FF00 / RGB(0,255,0) 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体不要使用 #00FF00 或接近纯绿色。强制避免：高桶身、深锅、深木桶、桶身高度超过开口高度 1/6、浅盘、小托盘、低矮盘子、正俯视扁圆盘、侧视碗、左右斜视、前沿缺口、画布大量留白、内部图案、红线、文字、水印、logo。
\ No newline at end of file
diff --git a/public/match3d-background-references/pot-fused-reference-candidate.prompt.txt b/public/match3d-background-references/pot-fused-reference-candidate.prompt.txt
index c64e9019d..2b5607835 100644
--- a/public/match3d-background-references/pot-fused-reference-candidate.prompt.txt
+++ b/public/match3d-background-references/pot-fused-reference-candidate.prompt.txt
@@ -1 +1 @@
-生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。主体只允许是一个大尺寸浅盘状或圆形竞技容器，用于移动端抓大鹅运行态中心棋盘覆盖层。构图必须严格满足：容器外轮廓接近画布四边，宽度约占画布 88%-92%，高度约占画布 84%-90%，中心在画布中心略偏下；只保留极少量外侧留白。视角必须是轻俯视 3/4 上方视角，可以看到厚实前沿、碗体外壁、内侧空间和横向椭圆形内口；不能是正俯视扁圆盘，不能是侧视碗，不能是小托盘。容器设计为题材中性、可复用的高品质休闲游戏 UI：浅米白陶瓷或浅蓝半透明玻璃质感，外沿清晰，内侧干净，可放置 2D 物品素材，边界高辨识，轻微内阴影和高光。背景必须是完全平整统一的纯绿色 #00FF00 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体绝对不要使用 #00FF00 或接近纯绿色；不要出现任何物品、角色、手、文字、水印、按钮、倒计时、分数、HUD、教程浮层、菜单、整页背景、棋盘格、网格线。
\ No newline at end of file
+生成一张 1024x1024 的 1:1 抓大鹅中心容器 UI 参考图。主体只允许是一个大尺寸浅盘状或圆形竞技容器，用于移动端抓大鹅运行态中心棋盘覆盖层。构图必须严格满足：容器外轮廓接近画布四边，宽度约占画布 88%-92%，高度约占画布 84%-90%，中心在画布中心略偏下；只保留极少量外侧留白。视角必须是轻俯视 3/4 上方视角，可以看到厚实前沿、碗体外壁、内侧空间和横向椭圆形内口；不能是正俯视扁圆盘，不能是侧视碗，不能是小托盘。容器设计为题材中性、可复用的高品质休闲游戏 UI：浅米白陶瓷或浅蓝半透明玻璃质感，外沿清晰，内侧干净，可放置 2D 物品素材，边界高辨识，轻微内阴影和高光。背景必须是完全平整统一的纯绿色 #00FF00 / RGB(0,255,0) 色键背景，用于后续抠透明；背景无纹理、无渐变、无阴影、无地面、无反射。容器本体绝对不要使用 #00FF00 或接近纯绿色；不要出现任何物品、角色、手、文字、水印、按钮、倒计时、分数、HUD、教程浮层、菜单、整页背景、棋盘格、网格线。
\ No newline at end of file
diff --git a/scripts/dev.mjs b/scripts/dev.mjs
index a76c20ee9..1e73b8a5b 100644
--- a/scripts/dev.mjs
+++ b/scripts/dev.mjs
@@ -37,7 +37,10 @@ const manifestPath = resolve(serverRsDir, 'Cargo.toml');
 const modulePath = resolve(serverRsDir, 'crates/spacetime-module');
 const viteCliPath = resolve(repoRoot, 'scripts/vite-cli.mjs');
 const adminWebDir = resolve(repoRoot, 'apps/admin-web');
-const LOCAL_DEV_RUSTC_WRAPPER_BYPASS = process.platform === 'win32' ? 'rustc' : '/usr/bin/env';
+function resolveLocalDevRustcWrapperBypass() {
+  // Windows 下不能把 rustc 自身当成 Cargo wrapper；空值会覆盖仓库 .cargo/config.toml 中的 sccache。
+  return process.platform === 'win32' ? '' : '/usr/bin/env';
+}
 
 const SERVICE_NAMES = ['spacetime', 'api-server', 'web', 'admin-web'];
 const SERVICE_ALIASES = new Map([
@@ -423,8 +426,9 @@ function buildLocalRustProcessEnv(env, options = {}) {
     return mergedEnv;
   }
 
-  mergedEnv.RUSTC_WRAPPER = LOCAL_DEV_RUSTC_WRAPPER_BYPASS;
-  mergedEnv.CARGO_BUILD_RUSTC_WRAPPER = LOCAL_DEV_RUSTC_WRAPPER_BYPASS;
+  const rustcWrapperBypass = resolveLocalDevRustcWrapperBypass();
+  mergedEnv.RUSTC_WRAPPER = rustcWrapperBypass;
+  mergedEnv.CARGO_BUILD_RUSTC_WRAPPER = rustcWrapperBypass;
   if (options.log !== false) {
     console.warn(
       '[dev:rust] 本地 dev 构建绕过项目 sccache wrapper，避免缓存进程异常阻断启动。',
diff --git a/scripts/dev.test.ts b/scripts/dev.test.ts
index 3cd31d33b..105113c67 100644
--- a/scripts/dev.test.ts
+++ b/scripts/dev.test.ts
@@ -213,6 +213,31 @@ describe('dev scheduler Rust build env', () => {
     expect(env.RUSTC_WRAPPER).toBe('custom-wrapper');
     expect(env.CARGO_BUILD_RUSTC_WRAPPER).toBe('custom-wrapper');
   });
+
+  test('Windows 下本地 dev Rust env 用空 wrapper 覆盖项目 sccache', () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+    Object.defineProperty(process, 'platform', {
+      configurable: true,
+      value: 'win32',
+    });
+
+    try {
+      const env = buildLocalRustProcessEnv(
+        {
+          RUSTC_WRAPPER: 'sccache',
+          CARGO_BUILD_RUSTC_WRAPPER: 'sccache',
+        },
+        {log: false},
+      );
+
+      expect(env.RUSTC_WRAPPER).toBe('');
+      expect(env.CARGO_BUILD_RUSTC_WRAPPER).toBe('');
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, 'platform', originalPlatform);
+      }
+    }
+  });
 });
 
 describe('dev scheduler stack state file', () => {
diff --git a/scripts/export-match3d-resource-pipeline.mjs b/scripts/export-match3d-resource-pipeline.mjs
index 8b6d11261..93f7839cb 100644
--- a/scripts/export-match3d-resource-pipeline.mjs
+++ b/scripts/export-match3d-resource-pipeline.mjs
@@ -97,7 +97,7 @@ function buildLevelScenePrompt(theme) {
 }
 
 function buildUiSpritesheetPrompt() {
-  return '提取画面中的UI元素，将返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮的顺序从上到下从左到右整理成纯绿色绿幕背景spritesheet。背景必须是统一纯绿色绿幕（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。UI 素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。';
+  return '提取画面中的UI元素，将返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮的顺序从上到下从左到右整理成单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景spritesheet。背景必须是统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。UI 素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。';
 }
 
 function buildBackgroundPrompt() {
@@ -105,7 +105,7 @@ function buildBackgroundPrompt() {
 }
 
 function buildItemSpritesheetPrompt() {
-  return '固定生成10行*10列spritesheet图，统一纯绿色绿幕背景（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。素材间距严格均匀分布，任意两个素材间距相同，物品来自参考图中画面中心容器中的2D素材。每一行包含两种物品，每种物品的五个不同形态。物品素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色物品只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。严禁出现两种高相似度的物品';
+  return '固定生成10行*10列spritesheet图，统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景，背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。素材间距严格均匀分布，任意两个素材间距相同，物品来自参考图中画面中心容器中的2D素材。每一行包含两种物品，每种物品的五个不同形态。物品素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色物品只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。严禁出现两种高相似度的物品';
 }
 
 function collectStringsByKey(value, targetKey, output) {
diff --git a/server-rs/crates/api-server/src/app.rs b/server-rs/crates/api-server/src/app.rs
index 5f02b46cf..e4fa80070 100644
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -42,7 +42,9 @@ pub fn build_router(state: AppState) -> Router {
         .merge(modules::internal::router(state.clone()))
         .merge(modules::auth::router(state.clone()))
         .merge(modules::profile::router(state.clone()))
+        .merge(modules::external_api::router(state.clone()))
         .merge(modules::assets::router(state.clone()))
+        .merge(modules::editor_project::router(state.clone()))
         .merge(modules::platform::router(state.clone()))
         .merge(modules::external_generation::router(state.clone()))
         .merge(modules::play_flow::router(state.clone()))
@@ -1468,6 +1470,140 @@ mod tests {
         assert!(!body_text.contains("length limit exceeded"));
     }
 
+    #[tokio::test]
+    async fn editor_character_animation_accepts_character_image_body_above_default_limit() {
+        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
+        let source_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
+        let request_body = serde_json::json!({
+            "sourceLayerId": "layer-character-large",
+            "sourceImageSrc": source_image_src,
+            "sourceWidth": 1024,
+            "sourceHeight": 1024,
+            "promptText": "待机呼吸循环。",
+            "resolution": "480p",
+            "ratio": "same",
+            "frameCount": 32,
+            "durationSeconds": 4,
+            "priceMudPoints": 40,
+            "model": "seedance2.0-fast"
+        })
+        .to_string();
+        assert!(request_body.len() > 2 * 1024 * 1024);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/editor/character-animations/generations")
+                    .header("content-type", "application/json")
+                    .body(Body::from(request_body))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("response body should collect")
+            .to_bytes();
+        let body_text = String::from_utf8_lossy(&body);
+        assert!(
+            body_text.contains("ARK_CHARACTER_VIDEO_BASE_URL"),
+            "handler should parse the oversized character source image before checking Ark config: {body_text}"
+        );
+        assert!(!body_text.contains("length limit exceeded"));
+    }
+
+    #[tokio::test]
+    async fn editor_ui_design_asset_extraction_accepts_image_body_above_default_limit() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let seed_user = seed_phone_user_with_password(&state, "13800138188", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &seed_user, "sess_editor_ui_extract_body");
+        let app = build_router(state);
+        let source_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
+        let request_body = serde_json::json!({
+            "sourceImageSrc": source_image_src,
+        })
+        .to_string();
+        assert!(request_body.len() > 2 * 1024 * 1024);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/editor/ui-designs/assets/extractions")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(request_body))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("response body should collect")
+            .to_bytes();
+        let body_text = String::from_utf8_lossy(&body);
+        assert!(
+            body_text.contains("VECTOR_ENGINE")
+                || body_text.contains("OPENAI")
+                || body_text.contains("配置"),
+            "handler should parse the oversized UI design image before checking image config: {body_text}"
+        );
+        assert!(!body_text.contains("length limit exceeded"));
+    }
+
+    #[tokio::test]
+    async fn editor_image_generation_accepts_reference_body_above_default_limit() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let seed_user = seed_phone_user_with_password(&state, "13800138028", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &seed_user, "sess_editor_image_reference_body");
+        let app = build_router(state);
+        let reference_image_src = format!("data:image/png;base64,{}", "A".repeat(3 * 1024 * 1024));
+        let request_body = serde_json::json!({
+            "prompt": "生成宣发素材",
+            "kind": "publication-material",
+            "size": "720x540",
+            "referenceImageSrcs": [reference_image_src],
+        })
+        .to_string();
+        assert!(request_body.len() > 2 * 1024 * 1024);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/editor/images/generations")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(request_body))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("response body should collect")
+            .to_bytes();
+        let body_text = String::from_utf8_lossy(&body);
+        assert!(
+            body_text.contains("VECTOR_ENGINE_BASE_URL"),
+            "handler should parse the oversized editor reference before checking VectorEngine config: {body_text}"
+        );
+        assert!(!body_text.contains("length limit exceeded"));
+    }
+
     #[tokio::test]
     async fn password_entry_rejects_unknown_phone_without_registration() {
         let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
diff --git a/server-rs/crates/api-server/src/assets.rs b/server-rs/crates/api-server/src/assets.rs
index 9a759b6b6..908576bae 100644
--- a/server-rs/crates/api-server/src/assets.rs
+++ b/server-rs/crates/api-server/src/assets.rs
@@ -56,6 +56,21 @@ pub async fn create_direct_upload_ticket(
     Extension(request_context): Extension<RequestContext>,
     Extension(authenticated): Extension<AuthenticatedAccessToken>,
     Json(payload): Json<CreateDirectUploadTicketRequest>,
+) -> Result<Json<Value>, AppError> {
+    create_direct_upload_ticket_for_owner(
+        &state,
+        &request_context,
+        authenticated.claims().user_id(),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn create_direct_upload_ticket_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    owner_user_id: &str,
+    payload: CreateDirectUploadTicketRequest,
 ) -> Result<Json<Value>, AppError> {
     let oss_client = state.oss_client().ok_or_else(|| {
         AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
@@ -95,9 +110,9 @@ pub async fn create_direct_upload_ticket(
     let upload = direct_upload_ticket_payload_from_oss(signed);
 
     record_asset_tracking_event(
-        &state,
-        &request_context,
-        &authenticated,
+        state,
+        request_context,
+        owner_user_id,
         "asset_upload_ticket_create",
         json!({
             "asset": {
@@ -117,7 +132,7 @@ pub async fn create_direct_upload_ticket(
     .await;
 
     Ok(json_success_body(
-        Some(&request_context),
+        Some(request_context),
         CreateDirectUploadTicketResponse { upload },
     ))
 }
@@ -126,6 +141,14 @@ pub async fn get_asset_read_url(
     State(state): State<AppState>,
     Extension(request_context): Extension<RequestContext>,
     Query(query): Query<GetReadUrlQuery>,
+) -> Result<Json<Value>, AppError> {
+    get_asset_read_url_with_query(&state, &request_context, query).await
+}
+
+pub(crate) async fn get_asset_read_url_with_query(
+    state: &AppState,
+    request_context: &RequestContext,
+    query: GetReadUrlQuery,
 ) -> Result<Json<Value>, AppError> {
     let oss_client = state.oss_client().ok_or_else(|| {
         AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
@@ -154,7 +177,7 @@ pub async fn get_asset_read_url(
         })?;
 
     Ok(json_success_body(
-        Some(&request_context),
+        Some(request_context),
         GetAssetReadUrlResponse {
             read: asset_read_url_payload_from_oss(signed),
         },
@@ -384,6 +407,21 @@ pub async fn confirm_asset_object(
     Extension(request_context): Extension<RequestContext>,
     Extension(authenticated): Extension<AuthenticatedAccessToken>,
     Json(payload): Json<ConfirmAssetObjectRequest>,
+) -> Result<Json<Value>, AppError> {
+    confirm_asset_object_for_owner(
+        &state,
+        &request_context,
+        authenticated.claims().user_id(),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn confirm_asset_object_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    owner_user_id: &str,
+    payload: ConfirmAssetObjectRequest,
 ) -> Result<Json<Value>, AppError> {
     let oss_client = state.oss_client().ok_or_else(|| {
         AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
@@ -395,13 +433,9 @@ pub async fn confirm_asset_object(
     let result = state
         .spacetime_client()
         .confirm_asset_object(
-            build_confirm_asset_object_upsert_input(
-                oss_client,
-                payload,
-                authenticated.claims().user_id(),
-            )
-            .await
-            .map_err(map_confirm_asset_object_prepare_error)?,
+            build_confirm_asset_object_upsert_input(oss_client, payload, owner_user_id)
+                .await
+                .map_err(map_confirm_asset_object_prepare_error)?,
         )
         .await
         .map_err(map_confirm_asset_object_error)?;
@@ -425,9 +459,9 @@ pub async fn confirm_asset_object(
     };
 
     record_asset_tracking_event(
-        &state,
-        &request_context,
-        &authenticated,
+        state,
+        request_context,
+        owner_user_id,
         "asset_upload_confirm",
         json!({
             "asset": {
@@ -451,7 +485,7 @@ pub async fn confirm_asset_object(
     .await;
 
     Ok(json_success_body(
-        Some(&request_context),
+        Some(request_context),
         ConfirmAssetObjectResponse { asset_object },
     ))
 }
@@ -498,7 +532,7 @@ pub async fn bind_asset_object_to_entity(
     record_asset_tracking_event(
         &state,
         &request_context,
-        &authenticated,
+        authenticated.claims().user_id(),
         "asset_bind",
         json!({
             "asset": {
@@ -526,12 +560,11 @@ pub async fn bind_asset_object_to_entity(
 async fn record_asset_tracking_event(
     state: &AppState,
     request_context: &RequestContext,
-    authenticated: &AuthenticatedAccessToken,
+    user_id: &str,
     event_key: &'static str,
     metadata: Value,
 ) {
-    let user_id = authenticated.claims().user_id().to_string();
-    let mut draft = TrackingEventDraft::user(event_key, "asset", user_id.as_str());
+    let mut draft = TrackingEventDraft::user(event_key, "asset", user_id);
     draft.metadata = metadata;
     record_tracking_event_after_success(state, request_context, draft).await;
 }
diff --git a/server-rs/crates/api-server/src/character_animation_assets.rs b/server-rs/crates/api-server/src/character_animation_assets.rs
index a2a5d0c64..58aed6907 100644
--- a/server-rs/crates/api-server/src/character_animation_assets.rs
+++ b/server-rs/crates/api-server/src/character_animation_assets.rs
@@ -41,6 +41,9 @@ use shared_contracts::assets::{
     CharacterRoleAssetWorkflowResolveRequest, CharacterRoleAssetWorkflowResponse,
     CharacterVisualDraftPayload, CharacterWorkflowCacheGetResponse, CharacterWorkflowCachePayload,
     CharacterWorkflowCacheSaveRequest, CharacterWorkflowCacheSaveResponse,
+    EditorCharacterAnimationFramePayload, EditorCharacterAnimationGenerateRequest,
+    EditorCharacterAnimationGenerateResponse, EditorVideoGenerateRequest,
+    EditorVideoGenerateResponse,
 };
 use spacetime_client::SpacetimeClientError;
 
@@ -60,6 +63,7 @@ use crate::{
 use tokio::time::sleep;
 
 const CHARACTER_ANIMATION_MODEL: &str = "doubao-seedance-2-0-fast-260128";
+const SEEDANCE_2_STANDARD_MODEL: &str = "doubao-seedance-2-0-260128";
 const CHARACTER_ANIMATION_ASSET_KIND: &str = "character_animation";
 const CHARACTER_ANIMATION_REFERENCE_ASSET_KIND: &str = "character_animation_reference_video";
 const CHARACTER_WORKFLOW_CACHE_ASSET_KIND: &str = "character_workflow_cache";
@@ -82,6 +86,23 @@ const FIXED_ARK_CHARACTER_VIDEO_RESOLUTION: &str = "480p";
 const FIXED_ARK_CHARACTER_VIDEO_RATIO: &str = "1:1";
 const FIXED_ARK_CHARACTER_VIDEO_DURATION_SECONDS: u32 = 4;
 const ARK_VIDEO_TASK_POLL_INTERVAL_MS: u64 = 5_000;
+const EDITOR_CHARACTER_ANIMATION_MODEL: &str = "seedance2.0-fast";
+const EDITOR_CHARACTER_ANIMATION_ASSET_KIND: &str = "editor_character_animation";
+const EDITOR_CHARACTER_ANIMATION_PROMPT_PREFIX: &str = "生成游戏角色动画，参考图作为首帧和尾帧，画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，禁止出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。\n动作描述：";
+const EDITOR_VIDEO_ASSET_KIND: &str = "editor_video";
+const EDITOR_VIDEO_ENTITY_KIND: &str = "editor_canvas";
+const EDITOR_VIDEO_SLOT: &str = "video_preview";
+const EDITOR_VIDEO_MODEL_SEEDANCE_2: &str = "seedance2.0";
+const EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST: &str = "seedance2.0-fast";
+const EDITOR_VIDEO_MODEL_KLING_3: &str = "kling3.0";
+const EDITOR_VIDEO_MODEL_KLING_3_OMNI: &str = "kling3.0-omni";
+const EDITOR_VIDEO_MODEL_VEO_3_1: &str = "veo3.1";
+const EDITOR_VIDEO_MODEL_VEO_3_1_FAST: &str = "veo3.1-fast";
+const EDITOR_VIDEO_REFERENCE_IMAGE_LIMIT: usize = 9;
+const EDITOR_VIDEO_REFERENCE_VIDEO_LIMIT: usize = 3;
+const EDITOR_VIDEO_REFERENCE_AUDIO_LIMIT: usize = 3;
+const EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES: usize = 64 * 1024 * 1024;
+const EDITOR_VIDEO_REFERENCE_READ_EXPIRE_SECONDS: u64 = 60 * 60;
 
 const BUILT_IN_MOTION_TEMPLATES: [MotionTemplate; 4] = [
     MotionTemplate {
@@ -114,6 +135,12 @@ const BUILT_IN_MOTION_TEMPLATES: [MotionTemplate; 4] = [
     },
 ];
 
+struct PersistedEditorVideo {
+    legacy_public_path: String,
+    object_key: String,
+    asset_object_id: String,
+}
+
 pub async fn list_character_animation_templates(
     Extension(request_context): Extension<RequestContext>,
 ) -> Json<Value> {
@@ -489,6 +516,167 @@ pub async fn generate_character_animation(
     ))
 }
 
+pub async fn generate_editor_character_animation(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<EditorCharacterAnimationGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    generate_editor_character_animation_for_owner(
+        state,
+        request_context,
+        "editor-character-animation".to_string(),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn generate_editor_character_animation_for_owner(
+    state: AppState,
+    request_context: RequestContext,
+    owner_user_id: String,
+    payload: Result<Json<EditorCharacterAnimationGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        character_animation_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-character-animation",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let normalized = normalize_editor_character_animation_request(payload)
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let settings = require_editor_character_animation_settings(&state, &normalized)
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let extraction_settings = resolve_backend_frame_extraction_settings(&state);
+    let http_client = build_upstream_http_client(settings.ark.request_timeout_ms)
+        .map_err(|error| character_animation_error_response(&request_context, error))?;
+    let task_id = generate_ai_task_id(current_utc_micros());
+
+    let result = async {
+        let source_data_url = resolve_media_source_as_data_url(
+            &state,
+            &http_client,
+            normalized.source_image_src.as_str(),
+            "sourceImageSrc",
+        )
+        .await?;
+        let generated = request_editor_character_animation_preview(
+            &state,
+            &http_client,
+            &settings,
+            owner_user_id.as_str(),
+            normalized.source_layer_id.as_str(),
+            task_id.as_str(),
+            normalized.prompt.as_str(),
+            source_data_url.as_str(),
+        )
+        .await?;
+        let frames = extract_and_persist_editor_character_animation_frames(
+            &state,
+            owner_user_id.as_str(),
+            normalized.source_layer_id.as_str(),
+            task_id.as_str(),
+            generated.preview_video_path.as_str(),
+            &normalized,
+            &extraction_settings,
+        )
+        .await?;
+
+        Ok::<_, AppError>((generated, frames))
+    }
+    .await;
+
+    let (generated, frames) =
+        result.map_err(|error| character_animation_error_response(&request_context, error))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorCharacterAnimationGenerateResponse {
+            ok: true,
+            task_id,
+            model: EDITOR_CHARACTER_ANIMATION_MODEL.to_string(),
+            prompt: generated.submitted_prompt,
+            preview_video_path: generated.preview_video_path,
+            frame_count: frames.len() as u32,
+            duration_seconds: normalized.duration_seconds,
+            frame_width: normalized.frame_width,
+            frame_height: normalized.frame_height,
+            fps: normalized.fps,
+            price_mud_points: normalized.price_mud_points,
+            frames,
+        },
+    ))
+}
+
+pub async fn generate_editor_video(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<EditorVideoGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    generate_editor_video_for_owner(state, request_context, "editor-video".to_string(), payload)
+        .await
+}
+
+pub(crate) async fn generate_editor_video_for_owner(
+    state: AppState,
+    request_context: RequestContext,
+    owner_user_id: String,
+    payload: Result<Json<EditorVideoGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        editor_video_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-video",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let normalized = normalize_editor_video_request(payload)
+        .map_err(|error| editor_video_error_response(&request_context, error))?;
+    let settings = require_editor_video_settings(&state, normalized.model.as_str())
+        .map_err(|error| editor_video_error_response(&request_context, error))?;
+    let http_client = build_upstream_http_client(settings.ark.request_timeout_ms)
+        .map_err(|error| editor_video_error_response(&request_context, error))?;
+    let task_id = generate_ai_task_id(current_utc_micros());
+
+    let generated = request_editor_video_preview(
+        &state,
+        &http_client,
+        &settings,
+        owner_user_id.as_str(),
+        task_id.as_str(),
+        &normalized,
+    )
+    .await
+    .map_err(|error| editor_video_error_response(&request_context, error))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorVideoGenerateResponse {
+            ok: true,
+            video_src: generated.preview_video_path,
+            object_key: generated.object_key,
+            asset_object_id: generated.asset_object_id,
+            width: normalized.width,
+            height: normalized.height,
+            source_type: "generated".to_string(),
+            prompt: normalized.prompt,
+            actual_prompt: Some(generated.submitted_prompt),
+            model: normalized.model,
+            provider: "VectorEngine".to_string(),
+            task_id,
+            duration_seconds: normalized.duration_seconds,
+            resolution: normalized.resolution,
+            price_mud_points: normalized.price_mud_points,
+        },
+    ))
+}
+
 pub async fn get_character_animation_job(
     State(state): State<AppState>,
     Extension(request_context): Extension<RequestContext>,
@@ -990,6 +1178,8 @@ async fn request_image_to_video_preview(
 
     Ok(GeneratedAnimationPreview {
         preview_video_path,
+        object_key: None,
+        asset_object_id: None,
         upstream_task_id,
         submitted_prompt,
         moderation_fallback_applied,
@@ -1248,6 +1438,291 @@ async fn put_generated_preview_video(
     Ok(put_result.legacy_public_path)
 }
 
+async fn request_editor_character_animation_preview(
+    state: &AppState,
+    http_client: &reqwest::Client,
+    settings: &EditorCharacterAnimationSettings,
+    owner_user_id: &str,
+    source_layer_id: &str,
+    task_id: &str,
+    prompt: &str,
+    source_frame_data_url: &str,
+) -> Result<GeneratedAnimationPreview, AppError> {
+    let upstream_task_id =
+        create_editor_ark_image_to_video_task(http_client, settings, prompt, source_frame_data_url)
+            .await?;
+    let video_url =
+        wait_for_ark_content_generation_task(http_client, &settings.ark, upstream_task_id.as_str())
+            .await?;
+    let preview_payload = download_generated_video(
+        http_client,
+        video_url.as_str(),
+        "下载画板角色动画视频失败。",
+    )
+    .await?;
+    let preview_video_path = put_generated_preview_video(
+        state,
+        owner_user_id,
+        source_layer_id,
+        "editor-character-animation",
+        task_id,
+        preview_payload,
+    )
+    .await?;
+
+    Ok(GeneratedAnimationPreview {
+        preview_video_path,
+        object_key: None,
+        asset_object_id: None,
+        upstream_task_id,
+        submitted_prompt: prompt.to_string(),
+        moderation_fallback_applied: false,
+    })
+}
+
+async fn request_editor_video_preview(
+    state: &AppState,
+    http_client: &reqwest::Client,
+    settings: &EditorVideoSettings,
+    owner_user_id: &str,
+    task_id: &str,
+    request: &NormalizedEditorVideoRequest,
+) -> Result<GeneratedAnimationPreview, AppError> {
+    let upstream_task_id =
+        create_editor_text_to_video_task(state, http_client, settings, request).await?;
+    let video_url =
+        wait_for_ark_content_generation_task(http_client, &settings.ark, upstream_task_id.as_str())
+            .await?;
+    let preview_payload =
+        download_generated_video(http_client, video_url.as_str(), "下载画板生成视频失败。").await?;
+    let persisted =
+        put_generated_editor_video(state, owner_user_id, task_id, request, preview_payload).await?;
+
+    Ok(GeneratedAnimationPreview {
+        preview_video_path: persisted.legacy_public_path,
+        object_key: Some(persisted.object_key),
+        asset_object_id: Some(persisted.asset_object_id),
+        upstream_task_id,
+        submitted_prompt: request.prompt.clone(),
+        moderation_fallback_applied: false,
+    })
+}
+
+async fn create_editor_text_to_video_task(
+    state: &AppState,
+    http_client: &reqwest::Client,
+    settings: &EditorVideoSettings,
+    request: &NormalizedEditorVideoRequest,
+) -> Result<String, AppError> {
+    let request_body = build_editor_video_ark_request_body(state, request)?;
+    let response = http_client
+        .post(format!(
+            "{}/contents/generations/tasks",
+            settings.ark.base_url
+        ))
+        .header(
+            reqwest::header::AUTHORIZATION,
+            format!("Bearer {}", settings.ark.api_key),
+        )
+        .header(reqwest::header::CONTENT_TYPE, "application/json")
+        .json(&request_body)
+        .send()
+        .await
+        .map_err(|error| {
+            map_character_animation_upstream_error(format!("请求画板视频服务失败：{error}"))
+        })?;
+
+    let status = response.status();
+    let body = response.text().await.map_err(|error| {
+        map_character_animation_upstream_error(format!("读取画板视频任务响应失败：{error}"))
+    })?;
+    if !status.is_success() {
+        return Err(parse_animation_upstream_error(
+            body.as_str(),
+            "创建画板视频任务失败。",
+        ));
+    }
+    let payload = parse_animation_json_payload(body.as_str(), "创建画板视频任务失败。")?;
+    extract_animation_task_id(&payload.payload).ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "editor-video",
+            "message": "画板视频任务未返回任务 id。",
+        }))
+    })
+}
+
+async fn put_generated_editor_video(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: &str,
+    request: &NormalizedEditorVideoRequest,
+    preview_payload: MediaPayload,
+) -> Result<PersistedEditorVideo, AppError> {
+    let content_type = preview_payload.mime_type.clone();
+    let put_result = put_character_animation_object(
+        state,
+        LegacyAssetPrefix::CharacterDrafts,
+        vec![
+            "editor-videos".to_string(),
+            sanitize_storage_segment(request.model.as_str(), "model"),
+            task_id.to_string(),
+        ],
+        format!("preview.{}", preview_payload.extension),
+        preview_payload.mime_type,
+        preview_payload.bytes,
+        build_asset_metadata(
+            EDITOR_VIDEO_ASSET_KIND,
+            owner_user_id,
+            EDITOR_VIDEO_ENTITY_KIND,
+            task_id,
+            EDITOR_VIDEO_SLOT,
+            request.model.as_str(),
+        ),
+    )
+    .await?;
+    let confirmed = confirm_editor_video_asset_object(
+        state,
+        owner_user_id,
+        task_id,
+        put_result.object_key.clone(),
+        content_type,
+    )
+    .await?;
+    Ok(PersistedEditorVideo {
+        legacy_public_path: put_result.legacy_public_path,
+        object_key: put_result.object_key,
+        asset_object_id: confirmed.record.asset_object_id,
+    })
+}
+
+async fn create_editor_ark_image_to_video_task(
+    http_client: &reqwest::Client,
+    settings: &EditorCharacterAnimationSettings,
+    prompt: &str,
+    source_frame_data_url: &str,
+) -> Result<String, AppError> {
+    let response = http_client
+        .post(format!(
+            "{}/contents/generations/tasks",
+            settings.ark.base_url
+        ))
+        .header(
+            reqwest::header::AUTHORIZATION,
+            format!("Bearer {}", settings.ark.api_key),
+        )
+        .header(reqwest::header::CONTENT_TYPE, "application/json")
+        .json(&json!({
+            "model": settings.ark.model,
+            "content": [
+                {
+                    "type": "text",
+                    "text": prompt,
+                },
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": source_frame_data_url,
+                    },
+                    "role": "first_frame",
+                },
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": source_frame_data_url,
+                    },
+                    "role": "last_frame",
+                }
+            ],
+            "resolution": settings.resolution,
+            "ratio": settings.ratio,
+            "duration": settings.duration_seconds,
+            "watermark": false,
+        }))
+        .send()
+        .await
+        .map_err(|error| {
+            map_character_animation_upstream_error(format!("请求 Ark 视频服务失败：{error}"))
+        })?;
+
+    let status = response.status();
+    let body = response.text().await.map_err(|error| {
+        map_character_animation_upstream_error(format!("读取 Ark 视频任务响应失败：{error}"))
+    })?;
+    if !status.is_success() {
+        return Err(parse_animation_upstream_error(
+            body.as_str(),
+            "创建画板角色动画视频任务失败。",
+        ));
+    }
+    let payload = parse_animation_json_payload(body.as_str(), "创建画板角色动画视频任务失败。")?;
+    extract_animation_task_id(&payload.payload).ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "ark",
+            "message": "画板角色动画视频任务未返回任务 id。",
+        }))
+    })
+}
+
+async fn extract_and_persist_editor_character_animation_frames(
+    state: &AppState,
+    owner_user_id: &str,
+    source_layer_id: &str,
+    task_id: &str,
+    preview_video_path: &str,
+    request: &NormalizedEditorCharacterAnimationRequest,
+    extraction_settings: &BackendFrameExtractionSettings,
+) -> Result<Vec<EditorCharacterAnimationFramePayload>, AppError> {
+    let plan = AnimationFrameExtractionPlan {
+        frame_count: request.frame_count,
+        apply_chroma_key: true,
+        sample_start_ratio: 0.0,
+        sample_end_ratio: 1.0,
+    };
+    let finalized_frames = extract_animation_frames_from_preview_video(
+        state,
+        preview_video_path,
+        request.frame_width,
+        request.frame_height,
+        extraction_settings,
+        &plan,
+        Some(request.duration_seconds as f64),
+    )
+    .await?;
+
+    let mut frame_payloads = Vec::with_capacity(finalized_frames.len());
+    for (index, frame) in finalized_frames.into_iter().enumerate() {
+        let put_result = put_character_animation_object(
+            state,
+            LegacyAssetPrefix::Animations,
+            vec![
+                "editor".to_string(),
+                sanitize_storage_segment(source_layer_id, "layer"),
+                task_id.to_string(),
+            ],
+            format!("frame{:02}.{}", index + 1, frame.extension),
+            frame.mime_type,
+            frame.bytes,
+            build_asset_metadata(
+                EDITOR_CHARACTER_ANIMATION_ASSET_KIND,
+                owner_user_id,
+                "editor_layer",
+                source_layer_id,
+                "animation_frame",
+                "editor-character-animation",
+            ),
+        )
+        .await?;
+        frame_payloads.push(EditorCharacterAnimationFramePayload {
+            frame_index: index as u32 + 1,
+            image_src: put_result.legacy_public_path,
+            width: request.frame_width,
+            height: request.frame_height,
+        });
+    }
+
+    Ok(frame_payloads)
+}
+
 async fn publish_animation_set(
     state: &AppState,
     owner_user_id: &str,
@@ -1373,6 +1848,7 @@ async fn publish_single_animation_action(
             frame_height,
             extraction_settings,
             &frame_plan,
+            None,
         )
         .await?
     } else {
@@ -1555,6 +2031,45 @@ async fn confirm_character_animation_asset_object(
     Ok(module_assets::ConfirmAssetObjectResult { record })
 }
 
+async fn confirm_editor_video_asset_object(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: &str,
+    object_key: String,
+    content_type: String,
+) -> Result<module_assets::ConfirmAssetObjectResult, AppError> {
+    let oss_client = require_oss_client(state)?;
+    let head = oss_client
+        .head_object(&reqwest::Client::new(), OssHeadObjectRequest { object_key })
+        .await
+        .map_err(map_character_animation_oss_error)?;
+    let now_micros = current_utc_micros();
+    let record = state
+        .spacetime_client()
+        .confirm_asset_object(
+            build_asset_object_upsert_input(
+                generate_asset_object_id(now_micros),
+                head.bucket,
+                head.object_key,
+                AssetObjectAccessPolicy::Private,
+                head.content_type.or(Some(content_type)),
+                head.content_length,
+                head.etag,
+                EDITOR_VIDEO_ASSET_KIND.to_string(),
+                Some(task_id.to_string()),
+                Some(owner_user_id.to_string()),
+                None,
+                Some(task_id.to_string()),
+                now_micros,
+            )
+            .map_err(map_asset_object_prepare_error)?,
+        )
+        .await
+        .map_err(map_character_animation_spacetime_error)?;
+
+    Ok(module_assets::ConfirmAssetObjectResult { record })
+}
+
 async fn bind_character_animation_asset(
     state: &AppState,
     owner_user_id: &str,
@@ -1864,6 +2379,680 @@ fn resolve_character_animation_model(payload: &CharacterAnimationGenerateRequest
     normalize_required_text(candidate, CHARACTER_ANIMATION_MODEL)
 }
 
+fn normalize_editor_character_animation_request(
+    payload: EditorCharacterAnimationGenerateRequest,
+) -> Result<NormalizedEditorCharacterAnimationRequest, AppError> {
+    let source_layer_id = normalize_required_text(payload.source_layer_id.as_str(), "");
+    if source_layer_id.is_empty() {
+        return Err(editor_character_animation_bad_request(
+            "sourceLayerId 不能为空。",
+        ));
+    }
+    let source_image_src = trim_optional_text(Some(payload.source_image_src.as_str()))
+        .ok_or_else(|| editor_character_animation_bad_request("sourceImageSrc 不能为空。"))?;
+    let prompt_text = payload
+        .prompt_text
+        .trim()
+        .chars()
+        .take(4000)
+        .collect::<String>();
+    if prompt_text.is_empty() {
+        return Err(editor_character_animation_bad_request("动画描述不能为空。"));
+    }
+    let resolution = normalize_editor_character_animation_resolution(payload.resolution.as_str())?;
+    let ratio = normalize_editor_character_animation_ratio(payload.ratio.as_str())?;
+    let frame_count = normalize_editor_character_animation_frame_count(payload.frame_count)?;
+    let duration_seconds =
+        normalize_editor_character_animation_duration(payload.duration_seconds, frame_count)?;
+    let expected_price =
+        crate::editor_generation_config::editor_character_animation_model_mud_points(
+            Some(payload.model.as_str()),
+            resolution,
+            duration_seconds,
+        );
+    if payload.price_mud_points != expected_price {
+        return Err(editor_character_animation_bad_request(format!(
+            "priceMudPoints 与分辨率和时长不一致，应为 {expected_price}。"
+        )));
+    }
+    if payload.model.trim() != EDITOR_CHARACTER_ANIMATION_MODEL {
+        return Err(editor_character_animation_bad_request(
+            "model 必须固定为 seedance2.0-fast。",
+        ));
+    }
+    let (frame_width, frame_height) = resolve_editor_character_animation_frame_size(
+        payload.source_width,
+        payload.source_height,
+        ratio,
+        resolution,
+    );
+    let prompt = build_editor_character_animation_prompt(prompt_text.as_str());
+
+    Ok(NormalizedEditorCharacterAnimationRequest {
+        source_layer_id,
+        source_image_src,
+        prompt,
+        resolution: resolution.to_string(),
+        ratio: resolve_editor_character_animation_provider_ratio(
+            ratio,
+            payload.source_width,
+            payload.source_height,
+        ),
+        frame_count,
+        duration_seconds,
+        price_mud_points: expected_price,
+        frame_width,
+        frame_height,
+        fps: (frame_count / duration_seconds).max(1),
+    })
+}
+
+fn require_editor_character_animation_settings(
+    state: &AppState,
+    request: &NormalizedEditorCharacterAnimationRequest,
+) -> Result<EditorCharacterAnimationSettings, AppError> {
+    let base_url = state
+        .config
+        .ark_character_video_base_url
+        .trim()
+        .trim_end_matches('/');
+    if base_url.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+                "provider": "ark",
+                "reason": "ARK_CHARACTER_VIDEO_BASE_URL 未配置",
+            })),
+        );
+    }
+    let api_key = state
+        .config
+        .ark_character_video_api_key
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| {
+            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+                "provider": "ark",
+                "reason": "ARK_CHARACTER_VIDEO_API_KEY 未配置",
+            }))
+        })?;
+    // 中文注释：画板角色动画入口产品侧固定为 Seedance 2.0 Fast，不继承通用角色视频环境模型覆盖。
+    Ok(EditorCharacterAnimationSettings {
+        ark: ArkVideoSettings {
+            base_url: base_url.to_string(),
+            api_key: api_key.to_string(),
+            request_timeout_ms: state.config.ark_character_video_request_timeout_ms.max(1),
+            model: CHARACTER_ANIMATION_MODEL.to_string(),
+        },
+        resolution: request.resolution.clone(),
+        ratio: request.ratio.clone(),
+        duration_seconds: request.duration_seconds,
+    })
+}
+
+fn normalize_editor_video_request(
+    payload: EditorVideoGenerateRequest,
+) -> Result<NormalizedEditorVideoRequest, AppError> {
+    let prompt = payload.prompt.trim().chars().take(4000).collect::<String>();
+    if prompt.is_empty() {
+        return Err(editor_video_bad_request("视频描述不能为空。"));
+    }
+    let model = normalize_editor_video_model(payload.model.as_str())?;
+    let aspect_ratio = normalize_editor_video_aspect_ratio(payload.aspect_ratio.as_str())?;
+    let resolution = normalize_editor_video_resolution(payload.resolution.as_str())?;
+    let duration_seconds = normalize_editor_video_duration(payload.duration_seconds)?;
+    if payload.mode.trim() != "std" {
+        return Err(editor_video_bad_request("mode 只支持 std。"));
+    }
+    let generate_audio = normalize_editor_video_sound(payload.sound.as_str())?;
+    if model == EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST && resolution == "1080p" {
+        return Err(editor_video_bad_request(
+            "seedance2.0-fast 不支持 1080p 清晰度。",
+        ));
+    }
+    let expected_price = crate::editor_generation_config::editor_video_model_generation_mud_points(
+        Some(model),
+        resolution,
+        duration_seconds,
+    );
+    if payload.price_mud_points != expected_price {
+        return Err(editor_video_bad_request(format!(
+            "priceMudPoints 与分辨率和时长不一致，应为 {expected_price}。"
+        )));
+    }
+    let references = normalize_editor_video_references(
+        model,
+        payload.reference_image_srcs,
+        payload.reference_video_srcs,
+        payload.reference_audio_srcs,
+    )?;
+    let (width, height) = resolve_editor_video_size(aspect_ratio, resolution);
+
+    Ok(NormalizedEditorVideoRequest {
+        prompt,
+        model: model.to_string(),
+        provider_model: resolve_editor_video_provider_model(model).to_string(),
+        aspect_ratio: aspect_ratio.to_string(),
+        resolution: resolution.to_string(),
+        duration_seconds,
+        generate_audio,
+        price_mud_points: expected_price,
+        width,
+        height,
+        reference_image_srcs: references.reference_image_srcs,
+        reference_video_srcs: references.reference_video_srcs,
+        reference_audio_srcs: references.reference_audio_srcs,
+    })
+}
+
+fn build_editor_video_ark_request_body(
+    state: &AppState,
+    request: &NormalizedEditorVideoRequest,
+) -> Result<Value, AppError> {
+    let content = build_editor_video_ark_content(state, request)?;
+    Ok(json!({
+        "model": request.provider_model,
+        "content": content,
+        "resolution": request.resolution,
+        "ratio": request.aspect_ratio,
+        "duration": request.duration_seconds,
+        "generate_audio": request.generate_audio,
+        "watermark": false,
+    }))
+}
+
+fn build_editor_video_ark_content(
+    state: &AppState,
+    request: &NormalizedEditorVideoRequest,
+) -> Result<Vec<Value>, AppError> {
+    let mut content = Vec::new();
+    if !request.prompt.trim().is_empty() {
+        content.push(json!({
+            "type": "text",
+            "text": request.prompt,
+        }));
+    }
+    let reference_image_urls = resolve_editor_video_reference_urls(
+        state,
+        request.reference_image_srcs.as_slice(),
+        "参考图片",
+        true,
+    )?;
+    let reference_video_urls = resolve_editor_video_reference_urls(
+        state,
+        request.reference_video_srcs.as_slice(),
+        "参考视频",
+        false,
+    )?;
+    let reference_audio_urls = resolve_editor_video_reference_urls(
+        state,
+        request.reference_audio_srcs.as_slice(),
+        "参考音频",
+        true,
+    )?;
+    content.extend(reference_image_urls.iter().map(|url| {
+        json!({
+            "type": "image_url",
+            "image_url": { "url": url },
+            "role": "reference_image",
+        })
+    }));
+    content.extend(reference_video_urls.iter().map(|url| {
+        json!({
+            "type": "video_url",
+            "video_url": { "url": url },
+            "role": "reference_video",
+        })
+    }));
+    content.extend(reference_audio_urls.iter().map(|url| {
+        json!({
+            "type": "audio_url",
+            "audio_url": { "url": url },
+            "role": "reference_audio",
+        })
+    }));
+    Ok(content)
+}
+
+fn resolve_editor_video_reference_urls(
+    state: &AppState,
+    sources: &[String],
+    label: &str,
+    allow_data_url: bool,
+) -> Result<Vec<String>, AppError> {
+    sources
+        .iter()
+        .map(|source| {
+            resolve_editor_video_reference_url(state, source.as_str(), label, allow_data_url)
+        })
+        .collect()
+}
+
+fn resolve_editor_video_reference_url(
+    state: &AppState,
+    source: &str,
+    label: &str,
+    allow_data_url: bool,
+) -> Result<String, AppError> {
+    let value = source.trim();
+    if value.starts_with("data:") {
+        if allow_data_url {
+            return Ok(value.to_string());
+        }
+        return Err(editor_video_bad_request(format!(
+            "{label}格式不支持，请使用官方支持的 URL、素材 ID 或画板资源路径。"
+        )));
+    }
+    if value.starts_with("asset://") {
+        return Ok(value.to_string());
+    }
+    if value.starts_with("http://") || value.starts_with("https://") {
+        return Ok(value.to_string());
+    }
+
+    let object_key = value.trim_start_matches('/');
+    if LegacyAssetPrefix::from_object_key(object_key).is_none() {
+        let format_hint = if allow_data_url {
+            "公网 URL、素材 ID、data URL 或画板资源路径"
+        } else {
+            "公网 URL、素材 ID 或画板资源路径"
+        };
+        return Err(editor_video_bad_request(format!(
+            "{label}必须是官方支持的{format_hint}。"
+        )));
+    }
+    let oss_client = state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置，无法为画板参考素材生成可访问 URL。",
+        }))
+    })?;
+    let signed = oss_client
+        .sign_get_object_url(OssSignedGetObjectUrlRequest {
+            object_key: object_key.to_string(),
+            expire_seconds: Some(EDITOR_VIDEO_REFERENCE_READ_EXPIRE_SECONDS),
+        })
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    Ok(signed.signed_url)
+}
+
+struct NormalizedEditorVideoReferences {
+    reference_image_srcs: Vec<String>,
+    reference_video_srcs: Vec<String>,
+    reference_audio_srcs: Vec<String>,
+}
+
+fn normalize_editor_video_references(
+    model: &str,
+    image_srcs: Vec<String>,
+    video_srcs: Vec<String>,
+    audio_srcs: Vec<String>,
+) -> Result<NormalizedEditorVideoReferences, AppError> {
+    let is_seedance =
+        model == EDITOR_VIDEO_MODEL_SEEDANCE_2 || model == EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST;
+    let image_srcs = normalize_reference_srcs(image_srcs);
+    let video_srcs = normalize_reference_srcs(video_srcs);
+    let audio_srcs = normalize_reference_srcs(audio_srcs);
+
+    if !is_seedance {
+        if image_srcs.is_empty() && video_srcs.is_empty() && audio_srcs.is_empty() {
+            return Ok(NormalizedEditorVideoReferences {
+                reference_image_srcs: Vec::new(),
+                reference_video_srcs: Vec::new(),
+                reference_audio_srcs: Vec::new(),
+            });
+        }
+        return Err(editor_video_bad_request(
+            "参考图片、参考视频和参考音频仅支持 Seedance 2.0 系列模型。",
+        ));
+    }
+    if image_srcs.len() > EDITOR_VIDEO_REFERENCE_IMAGE_LIMIT {
+        return Err(editor_video_bad_request("参考图片最多 9 张。"));
+    }
+    if video_srcs.len() > EDITOR_VIDEO_REFERENCE_VIDEO_LIMIT {
+        return Err(editor_video_bad_request("参考视频最多 3 个。"));
+    }
+    if audio_srcs.len() > EDITOR_VIDEO_REFERENCE_AUDIO_LIMIT {
+        return Err(editor_video_bad_request("参考音频最多 3 个。"));
+    }
+    if !audio_srcs.is_empty() && image_srcs.is_empty() && video_srcs.is_empty() {
+        return Err(editor_video_bad_request(
+            "参考音频必须搭配参考图片或参考视频。",
+        ));
+    }
+
+    for src in &image_srcs {
+        validate_editor_video_reference_src(
+            src,
+            "参考图片",
+            &["data:image/", "http://", "https://", "asset://"],
+            true,
+            "对应媒体 data URL",
+        )?;
+    }
+    for src in &video_srcs {
+        validate_editor_video_reference_src(
+            src,
+            "参考视频",
+            &["http://", "https://", "asset://"],
+            true,
+            "URL、素材 ID 或画板资源路径",
+        )?;
+    }
+    for src in &audio_srcs {
+        validate_editor_video_reference_src(
+            src,
+            "参考音频",
+            &["data:audio/", "http://", "https://", "asset://"],
+            true,
+            "对应媒体 data URL",
+        )?;
+    }
+
+    let request_bytes = image_srcs
+        .iter()
+        .chain(video_srcs.iter())
+        .chain(audio_srcs.iter())
+        .map(String::len)
+        .sum::<usize>();
+    if request_bytes > EDITOR_VIDEO_REFERENCE_REQUEST_LIMIT_BYTES {
+        return Err(editor_video_bad_request("参考文件总请求体不能超过 64MB。"));
+    }
+
+    Ok(NormalizedEditorVideoReferences {
+        reference_image_srcs: image_srcs,
+        reference_video_srcs: video_srcs,
+        reference_audio_srcs: audio_srcs,
+    })
+}
+
+fn normalize_reference_srcs(values: Vec<String>) -> Vec<String> {
+    values
+        .into_iter()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .collect()
+}
+
+fn validate_editor_video_reference_src(
+    value: &str,
+    label: &str,
+    allowed_prefixes: &[&str],
+    allow_generated_object_key: bool,
+    format_hint: &str,
+) -> Result<(), AppError> {
+    if allowed_prefixes
+        .iter()
+        .any(|prefix| value.starts_with(prefix))
+    {
+        return Ok(());
+    }
+    if allow_generated_object_key
+        && LegacyAssetPrefix::from_object_key(value.trim_start_matches('/')).is_some()
+    {
+        return Ok(());
+    }
+    Err(editor_video_bad_request(format!(
+        "{label}格式不支持，请使用官方支持的{format_hint}。"
+    )))
+}
+
+fn normalize_editor_video_model(value: &str) -> Result<&'static str, AppError> {
+    match value.trim() {
+        EDITOR_VIDEO_MODEL_SEEDANCE_2 => Ok(EDITOR_VIDEO_MODEL_SEEDANCE_2),
+        EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST => Ok(EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST),
+        EDITOR_VIDEO_MODEL_KLING_3 => Ok(EDITOR_VIDEO_MODEL_KLING_3),
+        EDITOR_VIDEO_MODEL_KLING_3_OMNI => Ok(EDITOR_VIDEO_MODEL_KLING_3_OMNI),
+        EDITOR_VIDEO_MODEL_VEO_3_1 => Ok(EDITOR_VIDEO_MODEL_VEO_3_1),
+        EDITOR_VIDEO_MODEL_VEO_3_1_FAST => Ok(EDITOR_VIDEO_MODEL_VEO_3_1_FAST),
+        _ => Err(editor_video_bad_request(
+            "model 只支持 seedance2.0、seedance2.0-fast、kling3.0、kling3.0-omni、veo3.1、veo3.1-fast。",
+        )),
+    }
+}
+
+fn resolve_editor_video_provider_model(model: &str) -> &str {
+    match model {
+        // 中文注释：Seedance 2.0 与 Seedance 2.0 Fast 必须映射到不同上游模型，避免生成视频误把标准版发到 fast 模型。
+        EDITOR_VIDEO_MODEL_SEEDANCE_2 => SEEDANCE_2_STANDARD_MODEL,
+        // 中文注释：Seedance 2.0 Fast 继续复用平台已有 fast seedance 上游模型。
+        EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST => CHARACTER_ANIMATION_MODEL,
+        _ => model,
+    }
+}
+
+fn normalize_editor_video_aspect_ratio(value: &str) -> Result<&'static str, AppError> {
+    match value.trim() {
+        "16:9" => Ok("16:9"),
+        "9:16" => Ok("9:16"),
+        "1:1" => Ok("1:1"),
+        "4:3" => Ok("4:3"),
+        "3:4" => Ok("3:4"),
+        "21:9" => Ok("21:9"),
+        _ => Err(editor_video_bad_request(
+            "aspectRatio 只支持 16:9、9:16、1:1、4:3、3:4 或 21:9。",
+        )),
+    }
+}
+
+fn normalize_editor_video_resolution(value: &str) -> Result<&'static str, AppError> {
+    match value.trim() {
+        "480p" => Ok("480p"),
+        "720p" => Ok("720p"),
+        "1080p" => Ok("1080p"),
+        _ => Err(editor_video_bad_request(
+            "resolution 只支持 480p、720p 或 1080p。",
+        )),
+    }
+}
+
+fn normalize_editor_video_duration(value: u32) -> Result<u32, AppError> {
+    if (4..=15).contains(&value) {
+        Ok(value)
+    } else {
+        Err(editor_video_bad_request(
+            "durationSeconds 只支持 4 到 15 秒的整数。",
+        ))
+    }
+}
+
+fn normalize_editor_video_sound(value: &str) -> Result<bool, AppError> {
+    match value.trim() {
+        "on" => Ok(true),
+        "off" => Ok(false),
+        _ => Err(editor_video_bad_request("sound 只支持 on 或 off。")),
+    }
+}
+
+fn resolve_editor_video_size(aspect_ratio: &str, resolution: &str) -> (u32, u32) {
+    let height = match resolution {
+        "1080p" => 1080,
+        "720p" => 720,
+        _ => 480,
+    };
+    let (ratio_width, ratio_height) = match aspect_ratio {
+        "9:16" => (9, 16),
+        "1:1" => (1, 1),
+        "4:3" => (4, 3),
+        "3:4" => (3, 4),
+        "21:9" => (21, 9),
+        _ => (16, 9),
+    };
+    let width = ((height * ratio_width) + ratio_height / 2) / ratio_height;
+    let even_width = if width % 2 == 0 { width } else { width + 1 };
+    (even_width, height)
+}
+
+fn require_editor_video_settings(
+    state: &AppState,
+    model: &str,
+) -> Result<EditorVideoSettings, AppError> {
+    let base_url = state
+        .config
+        .ark_character_video_base_url
+        .trim()
+        .trim_end_matches('/');
+    if base_url.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+                "provider": "ark",
+                "reason": "ARK_CHARACTER_VIDEO_BASE_URL 未配置",
+            })),
+        );
+    }
+    let api_key = state
+        .config
+        .ark_character_video_api_key
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| {
+            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+                "provider": "ark",
+                "reason": "ARK_CHARACTER_VIDEO_API_KEY 未配置",
+            }))
+        })?;
+
+    Ok(EditorVideoSettings {
+        ark: ArkVideoSettings {
+            base_url: base_url.to_string(),
+            api_key: api_key.to_string(),
+            request_timeout_ms: state.config.ark_character_video_request_timeout_ms.max(1),
+            model: resolve_editor_video_provider_model(model).to_string(),
+        },
+    })
+}
+
+fn editor_video_bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "editor-video",
+        "message": message.into(),
+    }))
+}
+
+fn build_editor_character_animation_prompt(prompt_text: &str) -> String {
+    format!(
+        "{}\n{}",
+        EDITOR_CHARACTER_ANIMATION_PROMPT_PREFIX,
+        prompt_text.trim()
+    )
+}
+
+fn normalize_editor_character_animation_resolution(value: &str) -> Result<&'static str, AppError> {
+    match value.trim() {
+        "480p" => Ok("480p"),
+        "720p" => Ok("720p"),
+        _ => Err(editor_character_animation_bad_request(
+            "resolution 只支持 480p 或 720p。",
+        )),
+    }
+}
+
+fn normalize_editor_character_animation_ratio(value: &str) -> Result<&'static str, AppError> {
+    match value.trim() {
+        "same" => Ok("same"),
+        "1:1" => Ok("1:1"),
+        "4:3" => Ok("4:3"),
+        "16:9" => Ok("16:9"),
+        "9:16" => Ok("9:16"),
+        "3:4" => Ok("3:4"),
+        _ => Err(editor_character_animation_bad_request(
+            "ratio 只支持 same、1:1、4:3、16:9、9:16、3:4。",
+        )),
+    }
+}
+
+fn normalize_editor_character_animation_frame_count(value: u32) -> Result<u32, AppError> {
+    match value {
+        32 | 40 | 48 => Ok(value),
+        _ => Err(editor_character_animation_bad_request(
+            "frameCount 只支持 32、40、48。",
+        )),
+    }
+}
+
+fn normalize_editor_character_animation_duration(
+    value: u32,
+    frame_count: u32,
+) -> Result<u32, AppError> {
+    let expected = match frame_count {
+        32 => 4,
+        40 => 5,
+        48 => 6,
+        _ => 0,
+    };
+    if value == expected {
+        Ok(value)
+    } else {
+        Err(editor_character_animation_bad_request(
+            "durationSeconds 必须与帧数组合为 32/4、40/5 或 48/6。",
+        ))
+    }
+}
+
+fn resolve_editor_character_animation_provider_ratio(
+    ratio: &str,
+    source_width: u32,
+    source_height: u32,
+) -> String {
+    if ratio != "same" {
+        return ratio.to_string();
+    }
+    if source_width == 0 || source_height == 0 {
+        return "1:1".to_string();
+    }
+    let normalized = source_width as f32 / source_height as f32;
+    [
+        ("1:1", 1.0f32),
+        ("4:3", 4.0 / 3.0),
+        ("16:9", 16.0 / 9.0),
+        ("9:16", 9.0 / 16.0),
+        ("3:4", 3.0 / 4.0),
+    ]
+    .into_iter()
+    .min_by(|(_, left), (_, right)| {
+        (normalized - *left)
+            .abs()
+            .partial_cmp(&(normalized - *right).abs())
+            .unwrap_or(std::cmp::Ordering::Equal)
+    })
+    .map(|(value, _)| value.to_string())
+    .unwrap_or_else(|| "1:1".to_string())
+}
+
+fn resolve_editor_character_animation_frame_size(
+    source_width: u32,
+    source_height: u32,
+    ratio: &str,
+    resolution: &str,
+) -> (u32, u32) {
+    let long_edge = if resolution == "720p" { 720 } else { 480 };
+    let (ratio_width, ratio_height) = match ratio {
+        "same" if source_width > 0 && source_height > 0 => (source_width, source_height),
+        "4:3" => (4, 3),
+        "16:9" => (16, 9),
+        "9:16" => (9, 16),
+        "3:4" => (3, 4),
+        _ => (1, 1),
+    };
+    if ratio_width >= ratio_height {
+        let height =
+            ((long_edge as f32 * ratio_height as f32 / ratio_width as f32).round() as u32).max(1);
+        (long_edge, height)
+    } else {
+        let width =
+            ((long_edge as f32 * ratio_width as f32 / ratio_height as f32).round() as u32).max(1);
+        (width, long_edge)
+    }
+}
+
+fn editor_character_animation_bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "editor-character-animation",
+        "message": message.into(),
+    }))
+}
+
 fn build_animation_generate_result_payload(generated: &CharacterAnimationGeneratedDraft) -> Value {
     match generated.preview_video_path.as_ref() {
         Some(preview_video_path) => json!({
@@ -1931,6 +3120,7 @@ async fn extract_animation_frames_from_preview_video(
     frame_height: u32,
     extraction_settings: &BackendFrameExtractionSettings,
     plan: &AnimationFrameExtractionPlan,
+    known_duration_seconds: Option<f64>,
 ) -> Result<Vec<FinalizedAnimationFrame>, AppError> {
     let preview_payload = load_media_source_payload(state, preview_video_path).await?;
     if !preview_payload.mime_type.starts_with("video/") {
@@ -1952,8 +3142,12 @@ async fn extract_animation_frames_from_preview_video(
     })?;
 
     let extraction_result = (|| {
-        let duration_seconds =
-            probe_video_duration_seconds(&input_path, extraction_settings)?.max(0.001);
+        let duration_seconds = probe_video_duration_seconds_or_known(
+            &input_path,
+            extraction_settings,
+            known_duration_seconds,
+        )?
+        .max(0.001);
         let mut finalized_frames = Vec::with_capacity(plan.frame_count as usize);
         for frame_index in 0..plan.frame_count {
             let target_seconds = compute_sample_time_seconds(
@@ -2034,6 +3228,31 @@ fn probe_video_duration_seconds(
     })
 }
 
+fn probe_video_duration_seconds_or_known(
+    input_path: &Path,
+    extraction_settings: &BackendFrameExtractionSettings,
+    known_duration_seconds: Option<f64>,
+) -> Result<f64, AppError> {
+    match probe_video_duration_seconds(input_path, extraction_settings) {
+        Ok(duration_seconds) => Ok(duration_seconds),
+        Err(error) if is_ffprobe_start_error(&error, extraction_settings.ffprobe_path.as_str()) => {
+            if let Some(duration_seconds) = known_duration_seconds
+                .filter(|duration_seconds| duration_seconds.is_finite() && *duration_seconds > 0.0)
+            {
+                return Ok(duration_seconds);
+            }
+            Err(error)
+        }
+        Err(error) => Err(error),
+    }
+}
+
+fn is_ffprobe_start_error(error: &AppError, ffprobe_path: &str) -> bool {
+    error.status_code() == StatusCode::SERVICE_UNAVAILABLE
+        && error.body_text().contains("无法启动进程")
+        && error.body_text().contains(ffprobe_path)
+}
+
 fn compute_sample_time_seconds(
     duration_seconds: f64,
     frame_index: u32,
@@ -2046,13 +3265,20 @@ fn compute_sample_time_seconds(
     let sample_start = duration_seconds * sample_start_ratio as f64;
     let sample_end = duration_seconds * sample_end_ratio as f64;
     let sample_window = (sample_end - sample_start).max(0.001);
-    let progress = if loop_mode {
-        frame_index as f64 / frame_count.max(1) as f64
+    let frame_count_f64 = frame_count.max(1) as f64;
+    let progress = if loop_mode || frame_count <= 1 || sample_end_ratio >= 1.0 {
+        frame_index as f64 / frame_count_f64
     } else {
         frame_index as f64 / frame_count.saturating_sub(1).max(1) as f64
     };
+    let frame_margin_seconds = (sample_window / frame_count_f64)
+        .max(0.05)
+        .min(sample_window);
+    let safe_sample_end = (sample_end - frame_margin_seconds)
+        .max(sample_start)
+        .min((duration_seconds - 0.001).max(0.0));
 
-    (sample_start + sample_window * progress).min((duration_seconds - 0.001).max(0.0))
+    (sample_start + sample_window * progress).min(safe_sample_end)
 }
 
 fn extract_video_frame_to_png(
@@ -2061,7 +3287,7 @@ fn extract_video_frame_to_png(
     target_seconds: f64,
     extraction_settings: &BackendFrameExtractionSettings,
 ) -> Result<(), AppError> {
-    run_process_with_timeout(
+    let output = run_process_with_timeout(
         &extraction_settings.ffmpeg_path,
         &[
             "-y",
@@ -2080,10 +3306,16 @@ fn extract_video_frame_to_png(
     )?;
 
     if !output_path.is_file() {
+        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+        let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
         return Err(
             AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                 "provider": "character-animation",
                 "message": "ffmpeg 已执行但未产出动作帧文件。",
+                "targetSeconds": target_seconds,
+                "outputPath": output_path.to_string_lossy(),
+                "stderr": stderr,
+                "stdout": stdout,
             })),
         );
     }
@@ -2534,7 +3766,7 @@ fn parse_animation_api_error_message(raw_text: &str, fallback_message: &str) ->
             .map(str::trim)
             .filter(|value| !value.is_empty())
         {
-            return message.to_string();
+            return localize_animation_api_error_message(message);
         }
         if let Some(message) = parsed
             .get("message")
@@ -2542,10 +3774,25 @@ fn parse_animation_api_error_message(raw_text: &str, fallback_message: &str) ->
             .map(str::trim)
             .filter(|value| !value.is_empty())
         {
-            return message.to_string();
+            return localize_animation_api_error_message(message);
         }
     }
-    raw_text.trim().to_string()
+    localize_animation_api_error_message(raw_text.trim())
+}
+
+fn localize_animation_api_error_message(message: &str) -> String {
+    let normalized = message.to_ascii_lowercase();
+    if normalized.contains("output video")
+        && normalized.contains("copyright")
+        && normalized.contains("restriction")
+    {
+        return "生成失败：输出视频可能涉及版权限制，请调整提示词或更换参考素材后重试。"
+            .to_string();
+    }
+    if normalized.contains("copyright") && normalized.contains("restriction") {
+        return "生成失败：内容可能涉及版权限制，请调整提示词或更换参考素材后重试。".to_string();
+    }
+    message.to_string()
 }
 
 fn parse_animation_upstream_error(raw_text: &str, fallback_message: &str) -> AppError {
@@ -3316,6 +4563,10 @@ fn character_animation_error_response(
     error.into_response_with_context(Some(request_context))
 }
 
+fn editor_video_error_response(request_context: &RequestContext, error: AppError) -> Response {
+    error.into_response_with_context(Some(request_context))
+}
+
 pub(crate) struct MotionTemplate {
     pub(crate) id: &'static str,
     pub(crate) label: &'static str,
@@ -3353,8 +4604,53 @@ struct ArkVideoSettings {
     model: String,
 }
 
+struct EditorCharacterAnimationSettings {
+    ark: ArkVideoSettings,
+    resolution: String,
+    ratio: String,
+    duration_seconds: u32,
+}
+
+struct EditorVideoSettings {
+    ark: ArkVideoSettings,
+}
+
+#[derive(Debug)]
+struct NormalizedEditorCharacterAnimationRequest {
+    source_layer_id: String,
+    source_image_src: String,
+    prompt: String,
+    resolution: String,
+    ratio: String,
+    frame_count: u32,
+    duration_seconds: u32,
+    price_mud_points: u32,
+    frame_width: u32,
+    frame_height: u32,
+    fps: u32,
+}
+
+#[derive(Debug)]
+struct NormalizedEditorVideoRequest {
+    prompt: String,
+    model: String,
+    provider_model: String,
+    aspect_ratio: String,
+    resolution: String,
+    duration_seconds: u32,
+    generate_audio: bool,
+    price_mud_points: u32,
+    width: u32,
+    height: u32,
+    reference_image_srcs: Vec<String>,
+    reference_video_srcs: Vec<String>,
+    reference_audio_srcs: Vec<String>,
+}
+
 struct GeneratedAnimationPreview {
     preview_video_path: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
     upstream_task_id: String,
     submitted_prompt: String,
     moderation_fallback_applied: bool,
@@ -3406,6 +4702,7 @@ struct PublishedAnimationAction {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::AppConfig;
 
     #[test]
     fn parse_video_data_url_accepts_mp4_payload() {
@@ -3548,4 +4845,522 @@ mod tests {
 
         assert_eq!(resolve_character_animation_model(&payload), "wan-move");
     }
+
+    #[test]
+    fn editor_character_animation_normalizes_seedance_request_contract() {
+        let normalized =
+            normalize_editor_character_animation_request(EditorCharacterAnimationGenerateRequest {
+                source_layer_id: " layer-hero ".to_string(),
+                source_image_src: "/generated-characters/hero/master.png".to_string(),
+                source_width: 768,
+                source_height: 1024,
+                prompt_text: "待机呼吸，轻微摆动。".to_string(),
+                resolution: "720p".to_string(),
+                ratio: "same".to_string(),
+                frame_count: 48,
+                duration_seconds: 6,
+                price_mud_points: 120,
+                model: EDITOR_CHARACTER_ANIMATION_MODEL.to_string(),
+            })
+            .expect("editor request should normalize");
+
+        assert_eq!(normalized.source_layer_id, "layer-hero");
+        assert_eq!(normalized.frame_count, 48);
+        assert_eq!(normalized.duration_seconds, 6);
+        assert_eq!(normalized.price_mud_points, 120);
+        assert_eq!(normalized.fps, 8);
+        assert_eq!(normalized.frame_width, 540);
+        assert_eq!(normalized.frame_height, 720);
+        assert_eq!(normalized.ratio, "3:4");
+    }
+
+    #[test]
+    fn editor_character_animation_uses_fast_seedance_provider_model() {
+        let config = AppConfig {
+            ark_character_video_base_url: "https://ark.example.com/api/v3".to_string(),
+            ark_character_video_api_key: Some("ark-key".to_string()),
+            ark_character_video_request_timeout_ms: 420_000,
+            ..AppConfig::default()
+        };
+        let state = AppState::new(config).expect("state should build");
+        let request =
+            normalize_editor_character_animation_request(EditorCharacterAnimationGenerateRequest {
+                source_layer_id: "layer-hero".to_string(),
+                source_image_src: "/generated-characters/hero/master.png".to_string(),
+                source_width: 1024,
+                source_height: 1024,
+                prompt_text: "待机呼吸".to_string(),
+                resolution: "480p".to_string(),
+                ratio: "same".to_string(),
+                frame_count: 32,
+                duration_seconds: 4,
+                price_mud_points: 40,
+                model: EDITOR_CHARACTER_ANIMATION_MODEL.to_string(),
+            })
+            .expect("editor request should normalize");
+
+        let settings = require_editor_character_animation_settings(&state, &request)
+            .expect("settings should normalize");
+
+        assert_eq!(settings.ark.model, CHARACTER_ANIMATION_MODEL);
+    }
+
+    #[test]
+    fn editor_character_animation_rejects_invalid_frame_duration_pair() {
+        let error =
+            normalize_editor_character_animation_request(EditorCharacterAnimationGenerateRequest {
+                source_layer_id: "layer-hero".to_string(),
+                source_image_src: "/generated-characters/hero/master.png".to_string(),
+                source_width: 1024,
+                source_height: 1024,
+                prompt_text: "奔跑".to_string(),
+                resolution: "480p".to_string(),
+                ratio: "1:1".to_string(),
+                frame_count: 48,
+                duration_seconds: 4,
+                price_mud_points: 40,
+                model: EDITOR_CHARACTER_ANIMATION_MODEL.to_string(),
+            })
+            .expect_err("invalid frame/duration pair should fail");
+
+        assert!(error.body_text().contains("durationSeconds 必须与帧数组合"));
+    }
+
+    #[test]
+    fn editor_character_animation_builds_required_green_screen_prompt() {
+        let prompt = build_editor_character_animation_prompt("行走两步后回到站姿。");
+
+        assert!(prompt.contains("生成游戏角色动画"));
+        assert!(prompt.contains("参考图作为首帧和尾帧"));
+        assert!(prompt.contains("背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
+        assert!(prompt.contains("动作描述：\n行走两步后回到站姿。"));
+    }
+
+    #[test]
+    fn editor_character_animation_price_depends_on_resolution_and_duration() {
+        assert_eq!(
+            crate::editor_generation_config::editor_character_animation_model_mud_points(
+                Some(EDITOR_CHARACTER_ANIMATION_MODEL),
+                "480p",
+                4,
+            ),
+            40
+        );
+        assert_eq!(
+            crate::editor_generation_config::editor_character_animation_model_mud_points(
+                Some(EDITOR_CHARACTER_ANIMATION_MODEL),
+                "720p",
+                6,
+            ),
+            120
+        );
+    }
+
+    #[test]
+    fn editor_character_animation_samples_last_frame_before_decode_tail() {
+        let last_frame_seconds = compute_sample_time_seconds(4.0, 31, 32, 0.0, 1.0, false);
+
+        assert!((last_frame_seconds - 3.875).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn editor_character_animation_extracts_final_sample_from_short_video() {
+        if Command::new("ffmpeg").arg("-version").output().is_err() {
+            return;
+        }
+
+        let temp_dir = create_animation_temp_dir().expect("temp dir should be created");
+        let input_path = temp_dir.join("short-preview.mp4");
+        let output_path = temp_dir.join("raw-frame-32.png");
+        let make_video_status = Command::new("ffmpeg")
+            .args([
+                "-y",
+                "-f",
+                "lavfi",
+                "-i",
+                "testsrc=size=160x120:rate=8:duration=4",
+                "-pix_fmt",
+                "yuv420p",
+                input_path.to_string_lossy().as_ref(),
+            ])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .status()
+            .expect("ffmpeg should start");
+        if !make_video_status.success() {
+            let _ = fs::remove_dir_all(&temp_dir);
+            return;
+        }
+        let target_seconds = compute_sample_time_seconds(4.0, 31, 32, 0.0, 1.0, false);
+        let settings = BackendFrameExtractionSettings {
+            ffmpeg_path: "ffmpeg".to_string(),
+            ffprobe_path: "ffprobe".to_string(),
+            timeout_ms: 10_000,
+        };
+
+        let result =
+            extract_video_frame_to_png(&input_path, &output_path, target_seconds, &settings);
+
+        let _ = fs::remove_dir_all(&temp_dir);
+        result.expect("safe final sample should produce a frame");
+    }
+
+    #[test]
+    fn editor_character_animation_uses_known_duration_when_ffprobe_is_missing() {
+        let settings = BackendFrameExtractionSettings {
+            ffmpeg_path: "ffmpeg".to_string(),
+            ffprobe_path: "__missing_ffprobe_for_editor_animation_test__".to_string(),
+            timeout_ms: 1_000,
+        };
+
+        let duration =
+            probe_video_duration_seconds_or_known(Path::new("preview.mp4"), &settings, Some(6.0))
+                .expect("known duration should cover a missing ffprobe binary");
+
+        assert_eq!(duration, 6.0);
+    }
+
+    #[test]
+    fn editor_character_animation_keeps_ffprobe_error_without_known_duration() {
+        let settings = BackendFrameExtractionSettings {
+            ffmpeg_path: "ffmpeg".to_string(),
+            ffprobe_path: "__missing_ffprobe_for_editor_animation_test__".to_string(),
+            timeout_ms: 1_000,
+        };
+
+        let error =
+            probe_video_duration_seconds_or_known(Path::new("preview.mp4"), &settings, None)
+                .expect_err("missing ffprobe should still fail without a trusted duration");
+
+        assert!(error.body_text().contains("无法启动进程"));
+    }
+
+    #[test]
+    fn editor_video_normalizes_lovart_model_contract() {
+        let normalized = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: " 让角色向镜头挥手 ".to_string(),
+            model: EDITOR_VIDEO_MODEL_KLING_3_OMNI.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 5,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 100,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("editor video request should normalize");
+
+        assert_eq!(normalized.prompt, "让角色向镜头挥手");
+        assert_eq!(normalized.model, EDITOR_VIDEO_MODEL_KLING_3_OMNI);
+        assert_eq!(normalized.provider_model, EDITOR_VIDEO_MODEL_KLING_3_OMNI);
+        assert_eq!(normalized.width, 854);
+        assert_eq!(normalized.height, 480);
+        assert_eq!(normalized.price_mud_points, 100);
+    }
+
+    #[test]
+    fn editor_video_seedance_fast_uses_existing_fast_seedance_model() {
+        let normalized = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "快速生成镜头推进。".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "720p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 80,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("seedance fast request should normalize");
+
+        assert_eq!(normalized.provider_model, CHARACTER_ANIMATION_MODEL);
+        assert_eq!(normalized.width, 1280);
+        assert_eq!(normalized.height, 720);
+    }
+
+    #[test]
+    fn editor_video_seedance_standard_uses_non_fast_seedance_model() {
+        let normalized = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "生成更稳定的电影感镜头。".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "720p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 96,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("seedance standard request should normalize");
+
+        assert_eq!(normalized.model, EDITOR_VIDEO_MODEL_SEEDANCE_2);
+        assert_eq!(normalized.provider_model, "doubao-seedance-2-0-260128");
+        assert_ne!(normalized.provider_model, CHARACTER_ANIMATION_MODEL);
+    }
+
+    #[test]
+    fn editor_video_supports_extra_ratios_duration_range_and_non_fast_1080p() {
+        let normalized = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "生成竖版电影感镜头。".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2.to_string(),
+            aspect_ratio: "9:16".to_string(),
+            duration_seconds: 15,
+            resolution: "1080p".to_string(),
+            mode: "std".to_string(),
+            sound: "on".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 720,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("seedance standard 1080p request should normalize");
+
+        assert_eq!(normalized.aspect_ratio, "9:16");
+        assert_eq!(normalized.width, 608);
+        assert_eq!(normalized.height, 1080);
+        assert!(normalized.generate_audio);
+    }
+
+    #[test]
+    fn editor_video_rejects_seedance_fast_1080p() {
+        let error = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "快速生成 1080p 镜头。".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "1080p".to_string(),
+            mode: "std".to_string(),
+            sound: "on".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 160,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect_err("seedance fast should reject 1080p");
+
+        assert!(error.body_text().contains("seedance2.0-fast 不支持 1080p"));
+    }
+
+    #[test]
+    fn editor_video_normalizes_seedance_multimodal_references() {
+        let normalized = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "参考素材生成视频".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 5,
+            resolution: "720p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 100,
+            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_video_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
+            ],
+            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+        })
+        .expect("seedance multimodal request should normalize");
+
+        assert_eq!(
+            normalized.reference_image_srcs,
+            vec!["data:image/png;base64,image"]
+        );
+        assert_eq!(
+            normalized.reference_video_srcs,
+            vec!["generated-character-drafts/editor/seedance-references/video/demo.mp4"]
+        );
+        assert_eq!(
+            normalized.reference_audio_srcs,
+            vec!["data:audio/mpeg;base64,audio"]
+        );
+    }
+
+    #[test]
+    fn editor_video_rejects_seedance_video_data_urls() {
+        let error = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "参考视频生成视频".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 40,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: vec!["data:video/mp4;base64,video".to_string()],
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect_err("Seedance reference videos must not accept Base64 data URLs");
+
+        assert!(error.body_text().contains("参考视频格式不支持"));
+    }
+
+    #[test]
+    fn editor_video_ark_body_sets_generate_audio_false_without_mode() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let request = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "参考素材生成视频".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 40,
+            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_video_srcs: vec!["https://assets.example.com/reference.mp4".to_string()],
+            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+        })
+        .expect("seedance multimodal request should normalize");
+
+        let body =
+            build_editor_video_ark_request_body(&state, &request).expect("ark body should build");
+
+        assert_eq!(body["generate_audio"], json!(false));
+        assert!(body.get("mode").is_none());
+        assert_eq!(body["content"][1]["role"], json!("reference_image"));
+        assert_eq!(body["content"][2]["role"], json!("reference_video"));
+        assert_eq!(body["content"][3]["role"], json!("reference_audio"));
+        assert_eq!(
+            body["content"][2]["video_url"]["url"],
+            json!("https://assets.example.com/reference.mp4")
+        );
+    }
+
+    #[test]
+    fn editor_video_ark_content_signs_generated_object_keys() {
+        let state = AppState::new(AppConfig {
+            oss_bucket: Some("genarrative-assets".to_string()),
+            oss_endpoint: Some("oss-cn-shanghai.aliyuncs.com".to_string()),
+            oss_access_key_id: Some("test-access-key-id".to_string()),
+            oss_access_key_secret: Some("test-access-key-secret".to_string()),
+            ..AppConfig::default()
+        })
+        .expect("state should build with OSS");
+        let request = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "参考视频生成视频".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 40,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
+            ],
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("seedance objectKey request should normalize");
+
+        let content = build_editor_video_ark_content(&state, &request)
+            .expect("ark content should sign object keys");
+        let signed_url = content[1]["video_url"]["url"]
+            .as_str()
+            .expect("video url should be string");
+
+        assert!(signed_url.starts_with("https://genarrative-assets.oss-cn-shanghai.aliyuncs.com/"));
+        assert!(
+            signed_url
+                .contains("generated-character-drafts/editor/seedance-references/video/demo.mp4")
+        );
+        assert!(signed_url.contains("x-oss-signature="));
+        assert_ne!(
+            signed_url,
+            "generated-character-drafts/editor/seedance-references/video/demo.mp4"
+        );
+    }
+
+    #[test]
+    fn editor_video_rejects_audio_only_seedance_references() {
+        let error = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "根据旁白生成视频".to_string(),
+            model: EDITOR_VIDEO_MODEL_SEEDANCE_2.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 4,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 48,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: vec!["data:audio/wav;base64,audio".to_string()],
+        })
+        .expect_err("audio-only references should fail");
+
+        assert!(
+            error
+                .body_text()
+                .contains("参考音频必须搭配参考图片或参考视频")
+        );
+    }
+
+    #[test]
+    fn seedance_copyright_restriction_error_is_localized() {
+        let raw = json!({
+            "error": {
+                "message": "The request failed because the output video may be related to copyright restrictions. Request id: 0217817823139540000000000000000000ffffac191c1d86f05"
+            }
+        })
+        .to_string();
+        let message = parse_animation_api_error_message(&raw, "创建画板视频任务失败。");
+
+        assert_eq!(
+            message,
+            "生成失败：输出视频可能涉及版权限制，请调整提示词或更换参考素材后重试。"
+        );
+        assert!(!message.contains("copyright"));
+        assert!(!message.contains("Request id"));
+    }
+
+    #[test]
+    fn raw_seedance_copyright_restriction_error_is_localized() {
+        let message = parse_animation_api_error_message(
+            "The request failed because the output video may be related to copyright restrictions. Request id: abc",
+            "创建画板视频任务失败。",
+        );
+
+        assert_eq!(
+            message,
+            "生成失败：输出视频可能涉及版权限制，请调整提示词或更换参考素材后重试。"
+        );
+    }
+
+    #[test]
+    fn editor_video_rejects_price_mismatch() {
+        let error = normalize_editor_video_request(EditorVideoGenerateRequest {
+            prompt: "生成镜头。".to_string(),
+            model: EDITOR_VIDEO_MODEL_VEO_3_1.to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 5,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 40,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect_err("wrong price should fail");
+
+        assert!(error.body_text().contains("priceMudPoints"));
+    }
 }
diff --git a/server-rs/crates/api-server/src/character_visual_assets.rs b/server-rs/crates/api-server/src/character_visual_assets.rs
index 08adcaa24..01de8aa41 100644
--- a/server-rs/crates/api-server/src/character_visual_assets.rs
+++ b/server-rs/crates/api-server/src/character_visual_assets.rs
@@ -1372,6 +1372,7 @@ fn collect_foreground_neighbor_color(
 }
 
 pub(crate) fn remove_background_from_rgba(pixels: &mut [u8], width: usize, height: usize) -> bool {
+    const INTERNAL_BACKGROUND_HOLE_MIN_PIXELS: usize = 16;
     const SOFT_EDGE_ALPHA_THRESHOLD: u8 = 224;
     const FOREGROUND_NEIGHBOR_ALPHA_THRESHOLD: u8 = 96;
 
@@ -1477,6 +1478,18 @@ pub(crate) fn remove_background_from_rgba(pixels: &mut [u8], width: usize, heigh
         }
     }
 
+    if mark_internal_background_holes(
+        pixels,
+        width,
+        height,
+        &mut background_mask,
+        &green_scores,
+        &white_scores,
+        INTERNAL_BACKGROUND_HOLE_MIN_PIXELS,
+    ) {
+        changed = true;
+    }
+
     for _ in 0..2 {
         let mut expanded_mask = background_mask.clone();
         for y in 0..height {
@@ -1712,6 +1725,138 @@ pub(crate) fn remove_background_from_rgba(pixels: &mut [u8], width: usize, heigh
     changed
 }
 
+fn mark_internal_background_holes(
+    pixels: &[u8],
+    width: usize,
+    height: usize,
+    background_mask: &mut [u8],
+    green_scores: &[f32],
+    white_scores: &[f32],
+    min_pixels: usize,
+) -> bool {
+    let pixel_count = width.saturating_mul(height);
+    if pixel_count == 0
+        || min_pixels == 0
+        || pixels.len() < pixel_count.saturating_mul(4)
+        || background_mask.len() < pixel_count
+        || green_scores.len() < pixel_count
+        || white_scores.len() < pixel_count
+    {
+        return false;
+    }
+
+    let mut visited = vec![false; pixel_count];
+    let mut queue = Vec::<usize>::new();
+    let mut component = Vec::<usize>::new();
+    let mut changed = false;
+
+    for start_index in 0..pixel_count {
+        if background_mask[start_index] != 0
+            || visited[start_index]
+            || !is_internal_background_hole_candidate(
+                pixels,
+                start_index,
+                green_scores[start_index],
+                white_scores[start_index],
+            )
+        {
+            continue;
+        }
+
+        queue.clear();
+        component.clear();
+        queue.push(start_index);
+        visited[start_index] = true;
+        let mut queue_index = 0usize;
+        let mut touches_border = false;
+
+        while queue_index < queue.len() {
+            let pixel_index = queue[queue_index];
+            queue_index += 1;
+            component.push(pixel_index);
+
+            let x = pixel_index % width;
+            let y = pixel_index / width;
+            if x == 0 || x == width.saturating_sub(1) || y == 0 || y == height.saturating_sub(1) {
+                touches_border = true;
+            }
+
+            let neighbors = [
+                if x > 0 { Some(pixel_index - 1) } else { None },
+                if x + 1 < width {
+                    Some(pixel_index + 1)
+                } else {
+                    None
+                },
+                if y > 0 {
+                    Some(pixel_index - width)
+                } else {
+                    None
+                },
+                if y + 1 < height {
+                    Some(pixel_index + width)
+                } else {
+                    None
+                },
+            ];
+
+            for next_index in neighbors.into_iter().flatten() {
+                if background_mask[next_index] != 0 || visited[next_index] {
+                    continue;
+                }
+                if !is_internal_background_hole_candidate(
+                    pixels,
+                    next_index,
+                    green_scores[next_index],
+                    white_scores[next_index],
+                ) {
+                    continue;
+                }
+                visited[next_index] = true;
+                queue.push(next_index);
+            }
+        }
+
+        if touches_border || component.len() < min_pixels {
+            continue;
+        }
+
+        for pixel_index in component.drain(..) {
+            background_mask[pixel_index] = 1;
+        }
+        changed = true;
+    }
+
+    changed
+}
+
+fn is_internal_background_hole_candidate(
+    pixels: &[u8],
+    pixel_index: usize,
+    green_score: f32,
+    white_score: f32,
+) -> bool {
+    let offset = pixel_index * 4;
+    let Some(pixel) = pixels.get(offset..offset + 4) else {
+        return false;
+    };
+    let red = pixel[0];
+    let green = pixel[1];
+    let blue = pixel[2];
+    let alpha = pixel[3];
+    if alpha < 40 {
+        return true;
+    }
+
+    let hard_green_key =
+        green_score >= 0.82 && green >= 180 && red <= 72 && blue <= 96 && green > red.max(blue);
+    let hard_white_key = white_score >= 0.62
+        && red.min(green).min(blue) >= 188
+        && red.max(green).max(blue) - red.min(green).min(blue) <= 42;
+
+    hard_green_key || hard_white_key
+}
+
 fn character_visual_error_response(request_context: &RequestContext, error: AppError) -> Response {
     error.into_response_with_context(Some(request_context))
 }
@@ -1759,7 +1904,7 @@ mod tests {
 
         assert!(prompt.contains("潮雾港向导"));
         assert!(prompt.contains("右向斜侧身"));
-        assert!(prompt.contains("纯绿色绿幕"));
+        assert!(prompt.contains("单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
     }
 
     #[test]
@@ -1792,6 +1937,33 @@ mod tests {
         assert!(is_image_test_moderation_error(&error));
     }
 
+    #[test]
+    fn character_background_alpha_removes_internal_green_holes() {
+        let width = 16;
+        let height = 16;
+        let mut image = image::RgbaImage::from_pixel(width, height, image::Rgba([0, 255, 0, 255]));
+        for y in 3..13 {
+            for x in 3..13 {
+                image.put_pixel(x, y, image::Rgba([188, 82, 45, 255]));
+            }
+        }
+        for y in 6..10 {
+            for x in 6..10 {
+                image.put_pixel(x, y, image::Rgba([0, 255, 0, 255]));
+            }
+        }
+
+        assert!(remove_background_from_rgba(
+            image.as_mut(),
+            width as usize,
+            height as usize
+        ));
+
+        assert_eq!(image.get_pixel(0, 0).0[3], 0);
+        assert_eq!(image.get_pixel(7, 7).0[3], 0);
+        assert_eq!(image.get_pixel(4, 4).0[3], 255);
+    }
+
     #[test]
     fn sanitize_storage_segment_keeps_legacy_safe_shape() {
         assert_eq!(
diff --git a/server-rs/crates/api-server/src/editor_generation_config.rs b/server-rs/crates/api-server/src/editor_generation_config.rs
new file mode 100644
index 000000000..af65fe504
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_generation_config.rs
@@ -0,0 +1,236 @@
+/// 图片画布编辑器生成类能力的泥点配置。
+///
+/// 中文注释：先用 api-server 静态配置收口价格事实源，避免继续把价格散落在
+/// 前端常量和具体 handler 内；后续若接后台配置，可只替换本模块读取来源。
+const EDITOR_IMAGE_MODEL_GPT_IMAGE_2: &str = "gpt-image-2";
+const EDITOR_IMAGE_MODEL_NANOBANANA2: &str = "gemini-3.1-flash-image-preview";
+const EDITOR_IMAGE_MODEL_NANOBANANA2_DISPLAY_ALIAS: &str = "nanobanana2";
+const EDITOR_IMAGE_MODEL_NANOBANANA_LEGACY_ALIAS: &str = "nano-banana";
+const EDITOR_IMAGE_MODEL_GENERATION_MUD_POINTS: u32 = 12;
+const EDITOR_IMAGE_MODEL_GPT_IMAGE_2_MUD_POINTS: u32 = 20;
+const EDITOR_SPEC_MODEL_GPT_IMAGE_2_MUD_POINTS: u32 = 5;
+
+pub(crate) const EDITOR_VIDEO_GENERATION_480P_MUD_POINTS_PER_SECOND: u32 = 10;
+pub(crate) const EDITOR_VIDEO_GENERATION_720P_MUD_POINTS_PER_SECOND: u32 = 20;
+pub(crate) const EDITOR_VIDEO_GENERATION_1080P_MUD_POINTS_PER_SECOND: u32 = 40;
+
+pub(crate) const EDITOR_CHARACTER_ANIMATION_480P_MUD_POINTS_PER_SECOND: u32 = 10;
+pub(crate) const EDITOR_CHARACTER_ANIMATION_720P_MUD_POINTS_PER_SECOND: u32 = 20;
+
+const EDITOR_VIDEO_MODEL_SEEDANCE_2: &str = "seedance2.0";
+const EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST: &str = "seedance2.0-fast";
+const EDITOR_VIDEO_MODEL_KLING_3: &str = "kling3.0";
+const EDITOR_VIDEO_MODEL_KLING_3_OMNI: &str = "kling3.0-omni";
+const EDITOR_VIDEO_MODEL_VEO_3_1: &str = "veo3.1";
+const EDITOR_VIDEO_MODEL_VEO_3_1_FAST: &str = "veo3.1-fast";
+const EDITOR_CHARACTER_ANIMATION_MODEL_SEEDANCE_2_FAST: &str = "seedance2.0-fast";
+pub(crate) const EDITOR_SOUND_EFFECT_MODEL_VIDU: &str = "audio1.0";
+pub(crate) const EDITOR_BACKGROUND_MUSIC_MODEL_SUNO: &str = "chirp-v5";
+const EDITOR_SOUND_EFFECT_MODEL_VIDU_MUD_POINTS: u32 = 10;
+const EDITOR_BACKGROUND_MUSIC_MODEL_SUNO_MUD_POINTS: u32 = 5;
+
+pub(crate) fn editor_image_model_generation_mud_points(model: Option<&str>) -> u32 {
+    match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(EDITOR_IMAGE_MODEL_GPT_IMAGE_2) => EDITOR_IMAGE_MODEL_GPT_IMAGE_2_MUD_POINTS,
+        Some(EDITOR_IMAGE_MODEL_NANOBANANA2)
+        | Some(EDITOR_IMAGE_MODEL_NANOBANANA2_DISPLAY_ALIAS)
+        | Some(EDITOR_IMAGE_MODEL_NANOBANANA_LEGACY_ALIAS) => {
+            EDITOR_IMAGE_MODEL_GENERATION_MUD_POINTS
+        }
+        _ => EDITOR_IMAGE_MODEL_GENERATION_MUD_POINTS,
+    }
+}
+
+pub(crate) fn editor_spec_model_generation_mud_points(model: Option<&str>) -> u32 {
+    match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(EDITOR_IMAGE_MODEL_GPT_IMAGE_2) => EDITOR_SPEC_MODEL_GPT_IMAGE_2_MUD_POINTS,
+        _ => EDITOR_SPEC_MODEL_GPT_IMAGE_2_MUD_POINTS,
+    }
+}
+
+pub(crate) fn editor_image_generation_mud_points(kind: Option<&str>, model: Option<&str>) -> u32 {
+    match kind.map(str::trim) {
+        Some("spec") => editor_spec_model_generation_mud_points(model),
+        Some("character" | "icon" | "ui-design" | "publication-material") => {
+            editor_image_model_generation_mud_points(model)
+        }
+        _ => editor_image_model_generation_mud_points(model),
+    }
+}
+
+fn editor_video_model_resolution_mud_points_per_second(
+    model: Option<&str>,
+    resolution: &str,
+) -> u32 {
+    let normalized_model = match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(
+            EDITOR_VIDEO_MODEL_SEEDANCE_2
+            | EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST
+            | EDITOR_VIDEO_MODEL_KLING_3
+            | EDITOR_VIDEO_MODEL_KLING_3_OMNI
+            | EDITOR_VIDEO_MODEL_VEO_3_1
+            | EDITOR_VIDEO_MODEL_VEO_3_1_FAST,
+        ) => model.unwrap_or_default().trim(),
+        _ => EDITOR_VIDEO_MODEL_SEEDANCE_2_FAST,
+    };
+    let (rate_480p, rate_720p, rate_1080p) = match normalized_model {
+        EDITOR_VIDEO_MODEL_SEEDANCE_2 => (12, 24, 48),
+        EDITOR_VIDEO_MODEL_KLING_3 => (15, 30, 60),
+        EDITOR_VIDEO_MODEL_KLING_3_OMNI => (20, 40, 80),
+        _ => (
+            EDITOR_VIDEO_GENERATION_480P_MUD_POINTS_PER_SECOND,
+            EDITOR_VIDEO_GENERATION_720P_MUD_POINTS_PER_SECOND,
+            EDITOR_VIDEO_GENERATION_1080P_MUD_POINTS_PER_SECOND,
+        ),
+    };
+    match resolution {
+        "1080p" => rate_1080p,
+        "720p" => rate_720p,
+        _ => rate_480p,
+    }
+}
+
+pub(crate) fn editor_video_model_generation_mud_points(
+    model: Option<&str>,
+    resolution: &str,
+    duration_seconds: u32,
+) -> u32 {
+    let per_second = editor_video_model_resolution_mud_points_per_second(model, resolution);
+    per_second * duration_seconds
+}
+
+pub(crate) fn editor_character_animation_model_mud_points(
+    model: Option<&str>,
+    resolution: &str,
+    duration_seconds: u32,
+) -> u32 {
+    let _normalized_model = match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(EDITOR_CHARACTER_ANIMATION_MODEL_SEEDANCE_2_FAST) => {
+            EDITOR_CHARACTER_ANIMATION_MODEL_SEEDANCE_2_FAST
+        }
+        _ => EDITOR_CHARACTER_ANIMATION_MODEL_SEEDANCE_2_FAST,
+    };
+    let per_second = if resolution == "720p" {
+        EDITOR_CHARACTER_ANIMATION_720P_MUD_POINTS_PER_SECOND
+    } else {
+        EDITOR_CHARACTER_ANIMATION_480P_MUD_POINTS_PER_SECOND
+    };
+    per_second * duration_seconds
+}
+
+pub(crate) fn editor_sound_effect_model_generation_mud_points(model: Option<&str>) -> u32 {
+    match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(EDITOR_SOUND_EFFECT_MODEL_VIDU) => EDITOR_SOUND_EFFECT_MODEL_VIDU_MUD_POINTS,
+        _ => EDITOR_SOUND_EFFECT_MODEL_VIDU_MUD_POINTS,
+    }
+}
+
+pub(crate) fn editor_background_music_model_generation_mud_points(model: Option<&str>) -> u32 {
+    match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(EDITOR_BACKGROUND_MUSIC_MODEL_SUNO) => EDITOR_BACKGROUND_MUSIC_MODEL_SUNO_MUD_POINTS,
+        _ => EDITOR_BACKGROUND_MUSIC_MODEL_SUNO_MUD_POINTS,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn editor_character_animation_price_uses_configured_resolution_rates() {
+        assert_eq!(
+            editor_character_animation_model_mud_points(Some("seedance2.0-fast"), "480p", 4),
+            40
+        );
+        assert_eq!(
+            editor_character_animation_model_mud_points(Some("seedance2.0-fast"), "720p", 6),
+            120
+        );
+    }
+
+    #[test]
+    fn editor_video_generation_price_uses_configured_resolution_rates() {
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("seedance2.0-fast"), "480p", 4),
+            40
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("seedance2.0-fast"), "720p", 5),
+            100
+        );
+    }
+
+    #[test]
+    fn editor_video_generation_price_uses_configured_model_rates() {
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("seedance2.0-fast"), "480p", 4),
+            40
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("seedance2.0"), "720p", 5),
+            120
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("kling3.0"), "480p", 5),
+            75
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("kling3.0-omni"), "720p", 4),
+            160
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("veo3.1"), "480p", 4),
+            40
+        );
+        assert_eq!(
+            editor_video_model_generation_mud_points(Some("veo3.1-fast"), "720p", 4),
+            80
+        );
+    }
+
+    #[test]
+    fn editor_audio_generation_price_uses_configured_model_rates() {
+        assert_eq!(
+            editor_sound_effect_model_generation_mud_points(Some("audio1.0")),
+            10
+        );
+        assert_eq!(
+            editor_background_music_model_generation_mud_points(Some("chirp-v5")),
+            5
+        );
+    }
+
+    #[test]
+    fn editor_image_generation_price_uses_configured_kind_rates() {
+        assert_eq!(editor_image_generation_mud_points(None, None), 12);
+        assert_eq!(editor_image_generation_mud_points(Some("spec"), None), 5);
+        assert_eq!(
+            editor_image_generation_mud_points(Some("character"), None),
+            12
+        );
+        assert_eq!(editor_image_generation_mud_points(Some("icon"), None), 12);
+        assert_eq!(
+            editor_image_generation_mud_points(Some("ui-design"), None),
+            12
+        );
+        assert_eq!(
+            editor_image_generation_mud_points(
+                Some("publication-material"),
+                Some("gemini-3.1-flash-image-preview")
+            ),
+            12
+        );
+        assert_eq!(
+            editor_image_generation_mud_points(Some("publication-material"), Some("nanobanana2")),
+            12
+        );
+        assert_eq!(
+            editor_image_generation_mud_points(Some("publication-material"), Some("nano-banana")),
+            12
+        );
+        assert_eq!(
+            editor_image_generation_mud_points(Some("publication-material"), Some("gpt-image-2")),
+            20
+        );
+    }
+}
diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
new file mode 100644
index 000000000..d84424d48
--- /dev/null
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -0,0 +1,3264 @@
+use std::{borrow::Cow, collections::BTreeMap};
+
+use axum::{
+    Json,
+    extract::{Extension, Path, State},
+    http::StatusCode,
+};
+use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
+use module_assets::{
+    AssetObjectAccessPolicy, AssetObjectFieldError, build_asset_object_upsert_input,
+    generate_asset_object_id,
+};
+use platform_image::{
+    DownloadedImage,
+    generated_asset_sheets::{
+        GeneratedAssetSheetAlphaOptions, GeneratedAssetSheetConnectedIcon,
+        apply_generated_asset_sheet_alpha_with_options,
+        slice_generated_icon_spritesheet_all_by_connected_components,
+        slice_generated_icon_spritesheet_by_connected_components,
+    },
+};
+use platform_oss::{LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_kernel::build_prefixed_uuid_id;
+use spacetime_client::{
+    EditorAssetCreateRecordInput, EditorAssetDeleteRecordInput, EditorAssetFolderCreateRecordInput,
+    EditorAssetFolderDeleteRecordInput, EditorAssetFolderRecord,
+    EditorAssetFolderUpdateRecordInput, EditorAssetLibraryRecord, EditorAssetRecord,
+    EditorAssetUpdateRecordInput, EditorCanvasRecord, EditorCanvasViewportRecord,
+    EditorProjectCreateRecordInput, EditorProjectDeleteRecordInput, EditorProjectGetRecordInput,
+    EditorProjectLayoutSaveRecordInput, EditorProjectRecord, EditorProjectRenameRecordInput,
+    EditorProjectResourceCreateRecordInput, EditorProjectResourceRecord, SpacetimeClientError,
+};
+
+use crate::{
+    api_response::json_success_body,
+    asset_billing::execute_billable_asset_operation_with_cost,
+    auth::AuthenticatedAccessToken,
+    generated_image_assets::{
+        GeneratedImageAssetAdapter, GeneratedImageAssetDataUrl,
+        adapter::{GeneratedImageAssetAdapterMetadata, GeneratedImageAssetPersistInput},
+        normalize_generated_image_asset_mime,
+    },
+    http_error::AppError,
+    openai_image_generation::{
+        DownloadedOpenAiImage, GPT_IMAGE_2_MODEL, OpenAiReferenceImage,
+        build_openai_image_http_client, create_openai_image_edit_with_references,
+        create_openai_image_edit_with_references_and_model,
+        create_openai_image_generation_with_model, create_openai_nanobanana_generate_content,
+        require_openai_image_settings,
+    },
+    platform_errors::map_oss_error,
+    request_context::RequestContext,
+    state::AppState,
+};
+
+pub(crate) const EDITOR_PROJECT_ID_PREFIX: &str = "editor-project-";
+pub(crate) const EDITOR_RESOURCE_ID_PREFIX: &str = "editor-resource-";
+pub(crate) const EDITOR_ASSET_FOLDER_ID_PREFIX: &str = "editor-asset-folder-";
+pub(crate) const EDITOR_ASSET_ID_PREFIX: &str = "editor-asset-";
+const EDITOR_LAYOUT_MAX_BYTES: usize = 256 * 1024;
+pub(crate) const EDITOR_PROJECT_DEFAULT_TITLE: &str = "未命名画布";
+const EDITOR_ASSET_METADATA_MAX_BYTES: usize = 64 * 1024;
+const EDITOR_ASSET_DEFAULT_FOLDER_ID: &str = "project";
+const EDITOR_IMAGE_GENERATION_SIZE: &str = "1024x1024";
+const EDITOR_IMAGE_MODEL_NANOBANANA2: &str = "gemini-3.1-flash-image-preview";
+const EDITOR_IMAGE_MODEL_NANOBANANA2_DISPLAY_ALIAS: &str = "nanobanana2";
+const EDITOR_IMAGE_MODEL_NANOBANANA_LEGACY_ALIAS: &str = "nano-banana";
+const EDITOR_ICON_DESCRIPTION_LIMIT: usize = 100;
+const EDITOR_UI_DESIGN_ASSET_EXTRACTION_PROMPT: &str = "提取画面中的所有独立并整理成spritesheet";
+const EDITOR_CHARACTER_IMAGE_ASSET_KIND: &str = "editor_character_image";
+const EDITOR_CHARACTER_IMAGE_ENTITY_KIND: &str = "editor_project";
+const EDITOR_CHARACTER_IMAGE_SLOT: &str = "character";
+const EDITOR_PUBLICATION_MATERIAL_ASSET_KIND: &str = "editor_publication_material";
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectCreateRequest {
+    title: Option<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCanvasViewportPayload {
+    x: f64,
+    y: f64,
+    scale: f64,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectLayoutSaveRequest {
+    pub(crate) viewport: EditorCanvasViewportPayload,
+    pub(crate) layers: Value,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectRenameRequest {
+    title: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectResourceCreateRequest {
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    source_resource_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetFolderCreateRequest {
+    label: String,
+    sort_order: Option<u32>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetFolderUpdateRequest {
+    label: Option<String>,
+    collapsed: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetCreateRequest {
+    folder_id: String,
+    label: String,
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetUpdateRequest {
+    label: Option<String>,
+    folder_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorImageGenerationRequest {
+    pub(crate) prompt: String,
+    pub(crate) size: Option<String>,
+    pub(crate) kind: Option<String>,
+    pub(crate) model: Option<String>,
+    pub(crate) aspect_ratio: Option<String>,
+    pub(crate) image_size: Option<String>,
+    pub(crate) reference_image_srcs: Option<Vec<String>>,
+    pub(crate) project_id: Option<String>,
+    pub(crate) asset_kind: Option<String>,
+    pub(crate) generation_inputs: Option<Value>,
+    pub(crate) asset_folder_id: Option<String>,
+    pub(crate) asset_label: Option<String>,
+    pub(crate) source_resource_id: Option<String>,
+    pub(crate) canvas_completion: Option<EditorCanvasGenerationCompletionRequest>,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCanvasGenerationCompletionRequest {
+    pub(crate) dialog_id: String,
+    pub(crate) title: String,
+    pub(crate) placeholder: EditorCanvasGenerationPlaceholderPayload,
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCanvasGenerationPlaceholderPayload {
+    pub(crate) x: f64,
+    pub(crate) y: f64,
+    pub(crate) width: f64,
+    pub(crate) height: f64,
+    pub(crate) original_width: f64,
+    pub(crate) original_height: f64,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorImageEditRequest {
+    pub(crate) prompt: String,
+    pub(crate) source_image_src: String,
+    pub(crate) project_id: Option<String>,
+    pub(crate) asset_kind: Option<String>,
+    pub(crate) generation_inputs: Option<Value>,
+    pub(crate) asset_folder_id: Option<String>,
+    pub(crate) asset_label: Option<String>,
+    pub(crate) source_resource_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetGenerationRequest {
+    pub(crate) reference_image_src: String,
+    pub(crate) icon_descriptions: Vec<String>,
+    pub(crate) model: Option<String>,
+    pub(crate) aspect_ratio: Option<String>,
+    pub(crate) image_size: Option<String>,
+    pub(crate) price_mud_points: u32,
+    pub(crate) project_id: Option<String>,
+    pub(crate) generation_inputs: Option<Value>,
+    pub(crate) asset_folder_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorUiDesignAssetExtractionRequest {
+    pub(crate) source_image_src: String,
+    pub(crate) project_id: Option<String>,
+    pub(crate) generation_inputs: Option<Value>,
+    pub(crate) asset_folder_id: Option<String>,
+    pub(crate) spritesheet_label: Option<String>,
+}
+
+pub(crate) struct EditorGenerationCaller {
+    pub(crate) owner_user_id: String,
+    pub(crate) audit_subject_user_id: Option<String>,
+    pub(crate) audit_project_id: Option<String>,
+}
+
+impl EditorGenerationCaller {
+    fn from_authenticated(authenticated: &AuthenticatedAccessToken) -> Self {
+        let owner_user_id = authenticated.claims().user_id().to_string();
+        Self {
+            audit_subject_user_id: Some(owner_user_id.clone()),
+            owner_user_id,
+            audit_project_id: None,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectResponse {
+    project: EditorProjectPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectRecentResponse {
+    project: Option<EditorProjectPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectListResponse {
+    projects: Vec<EditorProjectPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectDeleteResponse {
+    deleted_project_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectResourceResponse {
+    resource: EditorProjectResourcePayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetLibraryResponse {
+    library: EditorAssetLibraryPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetFolderResponse {
+    folder: EditorAssetFolderPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetFolderDeleteResponse {
+    library: EditorAssetLibraryPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetResponse {
+    asset: EditorAssetPayload,
+}
+
+#[derive(Debug)]
+struct EditorGeneratedAssetRecord {
+    resource: Option<EditorProjectResourcePayload>,
+    asset: Option<EditorAssetPayload>,
+}
+
+struct EditorCanvasGenerationCompletionResult {
+    layers: Value,
+    changed: bool,
+}
+
+#[derive(Debug)]
+struct PersistEditorGeneratedAssetInput {
+    project_id: Option<String>,
+    owner_user_id: String,
+    folder_id: Option<String>,
+    label: String,
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    prompt: String,
+    actual_prompt: Option<String>,
+    model: String,
+    provider: String,
+    task_id: String,
+    source_resource_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorImageGenerationResponse {
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: &'static str,
+    prompt: String,
+    actual_prompt: Option<String>,
+    model: String,
+    provider: &'static str,
+    task_id: String,
+    resource: Option<EditorProjectResourcePayload>,
+    asset: Option<EditorAssetPayload>,
+    project: Option<EditorProjectPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetIconResponse {
+    name: String,
+    image_src: String,
+    width: u32,
+    height: u32,
+    resource: Option<EditorProjectResourcePayload>,
+    asset: Option<EditorAssetPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetGenerationResponse {
+    spritesheet_image_src: String,
+    spritesheet_width: u32,
+    spritesheet_height: u32,
+    icon_image_srcs: Vec<EditorIconSpritesheetIconResponse>,
+    prompt: String,
+    actual_prompt: Option<String>,
+    model: String,
+    provider: &'static str,
+    task_id: String,
+    price_mud_points: u32,
+    spritesheet_resource: Option<EditorProjectResourcePayload>,
+    spritesheet_asset: Option<EditorAssetPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectPayload {
+    project_id: String,
+    title: String,
+    canvas: EditorCanvasPayload,
+    viewport: EditorCanvasViewportPayload,
+    layers: Value,
+    resources: Vec<EditorProjectResourcePayload>,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCanvasPayload {
+    canvas_id: String,
+    project_id: String,
+    title: String,
+    viewport: EditorCanvasViewportPayload,
+    layers: Value,
+    created_at: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorProjectResourcePayload {
+    resource_id: String,
+    project_id: String,
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    source_resource_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+    created_at: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetLibraryPayload {
+    folders: Vec<EditorAssetFolderPayload>,
+    assets: Vec<EditorAssetPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetFolderPayload {
+    folder_id: String,
+    label: String,
+    sort_order: u32,
+    collapsed: bool,
+    system_default: bool,
+    created_at: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAssetPayload {
+    asset_id: String,
+    folder_id: String,
+    label: String,
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+    created_at: String,
+    updated_at: String,
+}
+
+pub async fn load_recent_editor_project(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let project = state
+        .spacetime_client()
+        .get_recent_editor_project(owner_user_id)
+        .await
+        .map_err(map_editor_project_error)?
+        .map(editor_project_payload_from_record);
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectRecentResponse { project },
+    ))
+}
+
+pub async fn list_editor_projects(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let projects = state
+        .spacetime_client()
+        .list_editor_projects(owner_user_id)
+        .await
+        .map_err(map_editor_project_error)?
+        .into_iter()
+        .map(editor_project_payload_from_record)
+        .collect();
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectListResponse { projects },
+    ))
+}
+
+pub async fn create_editor_project(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorProjectCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let now_micros = current_utc_micros();
+    let title = payload
+        .title
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(|| EDITOR_PROJECT_DEFAULT_TITLE.to_string());
+    let project = state
+        .spacetime_client()
+        .create_editor_project(EditorProjectCreateRecordInput {
+            project_id: build_prefixed_uuid_id(EDITOR_PROJECT_ID_PREFIX),
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            title,
+            now_micros,
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn get_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let project = state
+        .spacetime_client()
+        .get_editor_project(EditorProjectGetRecordInput {
+            project_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn save_editor_project_layout(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorProjectLayoutSaveRequest>,
+) -> Result<Json<Value>, AppError> {
+    let layers_json = serialize_editor_layers(payload.layers)?;
+    let project = state
+        .spacetime_client()
+        .save_editor_project_layout(EditorProjectLayoutSaveRecordInput {
+            project_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            viewport: payload.viewport.into_record(),
+            layers_json,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn rename_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorProjectRenameRequest>,
+) -> Result<Json<Value>, AppError> {
+    let project = state
+        .spacetime_client()
+        .rename_editor_project(EditorProjectRenameRecordInput {
+            project_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            title: payload.title,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn delete_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let deleted_project_id = state
+        .spacetime_client()
+        .delete_editor_project(EditorProjectDeleteRecordInput {
+            project_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectDeleteResponse { deleted_project_id },
+    ))
+}
+
+pub async fn create_editor_project_resource(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorProjectResourceCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let generation_inputs_json =
+        serialize_editor_asset_metadata(payload.generation_inputs.clone())?;
+    let resource = state
+        .spacetime_client()
+        .create_editor_project_resource(EditorProjectResourceCreateRecordInput {
+            resource_id: build_prefixed_uuid_id(EDITOR_RESOURCE_ID_PREFIX),
+            project_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            asset_object_id: normalize_optional_string(payload.asset_object_id),
+            image_src: payload.image_src,
+            object_key: normalize_optional_string(payload.object_key),
+            width: payload.width,
+            height: payload.height,
+            source_type: payload.source_type,
+            prompt: normalize_optional_string(payload.prompt),
+            actual_prompt: normalize_optional_string(payload.actual_prompt),
+            model: normalize_optional_string(payload.model),
+            provider: normalize_optional_string(payload.provider),
+            task_id: normalize_optional_string(payload.task_id),
+            source_resource_id: normalize_optional_string(payload.source_resource_id),
+            asset_kind: normalize_optional_string(payload.asset_kind),
+            generation_inputs_json,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorProjectResourceResponse {
+            resource: editor_project_resource_payload_from_record(resource),
+        },
+    ))
+}
+
+pub async fn get_editor_asset_library(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let library = state
+        .spacetime_client()
+        .get_editor_asset_library(current_owner_user_id(&authenticated), current_utc_micros())
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetLibraryResponse {
+            library: editor_asset_library_payload_from_record(library),
+        },
+    ))
+}
+
+pub async fn create_editor_asset_folder(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorAssetFolderCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let folder = state
+        .spacetime_client()
+        .create_editor_asset_folder(EditorAssetFolderCreateRecordInput {
+            folder_id: build_prefixed_uuid_id(EDITOR_ASSET_FOLDER_ID_PREFIX),
+            owner_user_id: current_owner_user_id(&authenticated),
+            label: payload.label,
+            sort_order: payload.sort_order.unwrap_or(100),
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetFolderResponse {
+            folder: editor_asset_folder_payload_from_record(folder),
+        },
+    ))
+}
+
+pub async fn update_editor_asset_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorAssetFolderUpdateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let folder = state
+        .spacetime_client()
+        .update_editor_asset_folder(EditorAssetFolderUpdateRecordInput {
+            folder_id,
+            owner_user_id: current_owner_user_id(&authenticated),
+            label: normalize_optional_string(payload.label),
+            collapsed: payload.collapsed,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetFolderResponse {
+            folder: editor_asset_folder_payload_from_record(folder),
+        },
+    ))
+}
+
+pub async fn delete_editor_asset_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let library = state
+        .spacetime_client()
+        .delete_editor_asset_folder(EditorAssetFolderDeleteRecordInput {
+            folder_id,
+            owner_user_id: current_owner_user_id(&authenticated),
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetFolderDeleteResponse {
+            library: editor_asset_library_payload_from_record(library),
+        },
+    ))
+}
+
+pub async fn create_editor_asset(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorAssetCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let generation_inputs_json =
+        serialize_editor_asset_metadata(payload.generation_inputs.clone())?;
+    let asset = state
+        .spacetime_client()
+        .create_editor_asset(EditorAssetCreateRecordInput {
+            asset_id: build_prefixed_uuid_id(EDITOR_ASSET_ID_PREFIX),
+            owner_user_id: current_owner_user_id(&authenticated),
+            folder_id: payload.folder_id,
+            label: payload.label,
+            asset_object_id: normalize_optional_string(payload.asset_object_id),
+            image_src: payload.image_src,
+            object_key: normalize_optional_string(payload.object_key),
+            width: payload.width,
+            height: payload.height,
+            source_type: payload.source_type,
+            prompt: normalize_optional_string(payload.prompt),
+            actual_prompt: normalize_optional_string(payload.actual_prompt),
+            model: normalize_optional_string(payload.model),
+            provider: normalize_optional_string(payload.provider),
+            task_id: normalize_optional_string(payload.task_id),
+            asset_kind: normalize_optional_string(payload.asset_kind),
+            generation_inputs_json,
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn update_editor_asset(
+    State(state): State<AppState>,
+    Path(asset_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorAssetUpdateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let asset = state
+        .spacetime_client()
+        .update_editor_asset(EditorAssetUpdateRecordInput {
+            asset_id,
+            owner_user_id: current_owner_user_id(&authenticated),
+            label: normalize_optional_string(payload.label),
+            folder_id: normalize_optional_string(payload.folder_id),
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn delete_editor_asset(
+    State(state): State<AppState>,
+    Path(asset_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let asset = state
+        .spacetime_client()
+        .delete_editor_asset(EditorAssetDeleteRecordInput {
+            asset_id,
+            owner_user_id: current_owner_user_id(&authenticated),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn generate_editor_image(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorImageGenerationRequest>,
+) -> Result<Json<Value>, AppError> {
+    generate_editor_image_for_owner(
+        &state,
+        &request_context,
+        EditorGenerationCaller::from_authenticated(&authenticated),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn generate_editor_image_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    caller: EditorGenerationCaller,
+    payload: EditorImageGenerationRequest,
+) -> Result<Json<Value>, AppError> {
+    let role_setting = payload.prompt.trim().to_string();
+    if role_setting.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-image-generation",
+                "message": "生成提示词不能为空",
+            })),
+        );
+    }
+
+    let generation_options = normalize_editor_generation_options(
+        payload.model.as_deref(),
+        payload.aspect_ratio.as_deref(),
+        payload.image_size.as_deref(),
+    );
+    let has_dimension_options = payload.aspect_ratio.is_some() || payload.image_size.is_some();
+    let normalized_kind = payload.kind.as_deref().map(str::trim);
+    let is_character_generation = matches!(normalized_kind, Some("character"));
+    let is_ui_design_generation = matches!(normalized_kind, Some("ui-design"));
+    let is_publication_material_generation =
+        matches!(normalized_kind, Some("publication-material"));
+    let image_size = resolve_editor_image_request_size(
+        normalized_kind,
+        payload.size.as_deref(),
+        has_dimension_options,
+        &generation_options,
+    );
+    let submitted_prompt = if is_character_generation {
+        build_editor_character_image_prompt(role_setting.as_str())
+    } else if is_ui_design_generation {
+        build_editor_ui_design_prompt(
+            role_setting.as_str(),
+            payload
+                .reference_image_srcs
+                .as_ref()
+                .is_some_and(|references| {
+                    references.iter().any(|source| !source.trim().is_empty())
+                }),
+        )
+    } else {
+        role_setting.clone()
+    };
+    let failure_context = match normalized_kind {
+        Some("character") => "图片画布生成角色形象",
+        Some("spec") => "图片画布生成规范",
+        Some("quick-edit") => "图片画布快速编辑图片",
+        Some("ui-design") => "图片画布生成UI设计图",
+        Some("publication-material") => "图片画布生成宣发素材",
+        _ => "图片画布生成图片",
+    };
+    let reference_limit = if matches!(normalized_kind, Some("quick-edit")) {
+        9
+    } else {
+        5
+    };
+    let reference_sources = payload
+        .reference_image_srcs
+        .unwrap_or_default()
+        .into_iter()
+        .map(|source| source.trim().to_string())
+        .filter(|source| !source.is_empty())
+        .take(reference_limit)
+        .collect::<Vec<_>>();
+    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
+        request_context,
+        caller.audit_subject_user_id.clone(),
+        caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+    );
+    let http_client = build_openai_image_http_client(&settings)?;
+    let negative_prompt = Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体");
+    let reference_images = if reference_sources.is_empty() {
+        Vec::new()
+    } else {
+        reference_sources
+            .iter()
+            .map(|source| parse_editor_reference_image(source.as_str()))
+            .collect::<Result<Vec<_>, _>>()?
+    };
+    let generation_options = if is_ui_design_generation {
+        normalize_editor_generation_options(
+            Some(GPT_IMAGE_2_MODEL),
+            payload.aspect_ratio.as_deref(),
+            payload.image_size.as_deref(),
+        )
+    } else {
+        generation_options
+    };
+    let image_size = if is_ui_design_generation {
+        Cow::Owned(generation_options.size.clone())
+    } else {
+        image_size
+    };
+    let configured_price_mud_points =
+        crate::editor_generation_config::editor_image_generation_mud_points(
+            normalized_kind,
+            Some(generation_options.model),
+        );
+    let generate_operation = async {
+        if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+            create_openai_nanobanana_generate_content(
+                &http_client,
+                &settings,
+                generation_options.model,
+                submitted_prompt.as_str(),
+                negative_prompt,
+                generation_options.aspect_ratio,
+                generation_options.provider_image_size,
+                reference_images.as_slice(),
+                failure_context,
+            )
+            .await
+        } else if reference_images.is_empty() {
+            create_openai_image_generation_with_model(
+                &http_client,
+                &settings,
+                generation_options.model,
+                submitted_prompt.as_str(),
+                negative_prompt,
+                image_size.as_ref(),
+                1,
+                &[],
+                failure_context,
+            )
+            .await
+        } else {
+            create_openai_image_edit_with_references_and_model(
+                &http_client,
+                &settings,
+                generation_options.model,
+                submitted_prompt.as_str(),
+                negative_prompt,
+                image_size.as_ref(),
+                1,
+                reference_images.as_slice(),
+                failure_context,
+            )
+            .await
+        }
+    };
+    let generated = if is_publication_material_generation {
+        execute_billable_asset_operation_with_cost(
+            state,
+            caller.owner_user_id.as_str(),
+            EDITOR_PUBLICATION_MATERIAL_ASSET_KIND,
+            request_context.request_id(),
+            u64::from(configured_price_mud_points),
+            generate_operation,
+        )
+        .await?
+    } else {
+        generate_operation.await?
+    };
+    let mut image = generated.images.into_iter().next().ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "vector-engine",
+            "message": "VectorEngine 未返回图片",
+        }))
+    })?;
+    if is_character_generation {
+        image = prepare_editor_character_image_for_response(image);
+    }
+
+    let (width, height) = image::load_from_memory(image.bytes.as_slice())
+        .map(|image| (image.width(), image.height()))
+        .unwrap_or((1024, 1024));
+    let persisted = if is_character_generation {
+        Some(
+            persist_editor_generated_image(
+                state,
+                caller.owner_user_id.as_str(),
+                generated.task_id.as_str(),
+                &image,
+                submitted_prompt.as_str(),
+                generated.actual_prompt.as_deref(),
+                EDITOR_CHARACTER_IMAGE_ASSET_KIND,
+                "character-images",
+                EDITOR_CHARACTER_IMAGE_SLOT,
+            )
+            .await?,
+        )
+    } else {
+        None
+    };
+    let image_src = format!(
+        "data:{};base64,{}",
+        image.mime_type,
+        BASE64_STANDARD.encode(image.bytes.as_slice())
+    );
+    let generated_asset = persist_editor_generated_asset(
+        state,
+        PersistEditorGeneratedAssetInput {
+            project_id: payload.project_id.clone(),
+            owner_user_id: caller.owner_user_id.clone(),
+            folder_id: payload.asset_folder_id,
+            label: normalize_optional_string(payload.asset_label)
+                .unwrap_or_else(|| role_setting.clone()),
+            image_src: image_src.clone(),
+            object_key: persisted.as_ref().map(|asset| asset.object_key.clone()),
+            asset_object_id: persisted
+                .as_ref()
+                .map(|asset| asset.asset_object_id.clone()),
+            width,
+            height,
+            prompt: role_setting.clone(),
+            actual_prompt: generated.actual_prompt.clone(),
+            model: generation_options.model.to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: generated.task_id.clone(),
+            source_resource_id: payload.source_resource_id,
+            asset_kind: payload.asset_kind,
+            generation_inputs: payload.generation_inputs,
+        },
+    )
+    .await?;
+    let completed_project = complete_editor_canvas_generation(
+        state,
+        caller.owner_user_id.as_str(),
+        payload.project_id.as_deref(),
+        payload.canvas_completion.as_ref(),
+        generated_asset.resource.as_ref(),
+    )
+    .await?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorImageGenerationResponse {
+            image_src,
+            object_key: persisted.as_ref().map(|asset| asset.object_key.clone()),
+            asset_object_id: persisted
+                .as_ref()
+                .map(|asset| asset.asset_object_id.clone()),
+            width,
+            height,
+            source_type: "generated",
+            prompt: role_setting,
+            actual_prompt: generated.actual_prompt,
+            model: generation_options.model.to_string(),
+            provider: "VectorEngine",
+            task_id: generated.task_id,
+            resource: generated_asset.resource,
+            asset: generated_asset.asset,
+            project: completed_project,
+        },
+    ))
+}
+
+fn normalize_editor_image_generation_size(size: Option<&str>) -> Cow<'static, str> {
+    match size.map(str::trim).filter(|value| !value.is_empty()) {
+        Some("1024x1024") | Some("1024*1024") | Some("1:1") => Cow::Borrowed("1024x1024"),
+        Some("1536x1024") | Some("1536*1024") | Some("16:9") => Cow::Borrowed("1536x1024"),
+        Some("2048x1152") | Some("2048*1152") | Some("1920x1080") | Some("1920*1080")
+        | Some("2k-16:9") => Cow::Borrowed("2048x1152"),
+        Some("1024x1536") | Some("1024*1536") | Some("9:16") => Cow::Borrowed("1024x1536"),
+        Some(value) if is_editor_custom_image_size(value) => Cow::Owned(value.to_string()),
+        _ => Cow::Borrowed(EDITOR_IMAGE_GENERATION_SIZE),
+    }
+}
+
+fn resolve_editor_image_request_size(
+    normalized_kind: Option<&str>,
+    payload_size: Option<&str>,
+    has_dimension_options: bool,
+    generation_options: &EditorGenerationOptions,
+) -> Cow<'static, str> {
+    let legacy_size = normalize_editor_image_generation_size(payload_size);
+    let has_explicit_payload_size = payload_size
+        .map(str::trim)
+        .is_some_and(|value| !value.is_empty());
+    if matches!(normalized_kind, Some("publication-material")) && has_explicit_payload_size {
+        return legacy_size;
+    }
+    if has_dimension_options {
+        return Cow::Owned(generation_options.size.clone());
+    }
+    legacy_size
+}
+
+fn is_editor_custom_image_size(value: &str) -> bool {
+    let Some((width, height)) = value.split_once('x') else {
+        return false;
+    };
+    let Ok(width) = width.parse::<u32>() else {
+        return false;
+    };
+    let Ok(height) = height.parse::<u32>() else {
+        return false;
+    };
+    (64..=4096).contains(&width) && (64..=4096).contains(&height)
+}
+
+fn normalize_editor_generation_options(
+    model: Option<&str>,
+    aspect_ratio: Option<&str>,
+    image_size: Option<&str>,
+) -> EditorGenerationOptions {
+    let normalized_model = match model.map(str::trim).filter(|value| !value.is_empty()) {
+        Some(GPT_IMAGE_2_MODEL) => GPT_IMAGE_2_MODEL,
+        Some(
+            EDITOR_IMAGE_MODEL_NANOBANANA2
+            | EDITOR_IMAGE_MODEL_NANOBANANA2_DISPLAY_ALIAS
+            | EDITOR_IMAGE_MODEL_NANOBANANA_LEGACY_ALIAS,
+        ) => EDITOR_IMAGE_MODEL_NANOBANANA2,
+        // 中文注释：未显式传模型的旧普通生成、快速编辑和生成规范继续走 gpt-image-2；
+        // 角色 / 图标素材入口由前端显式传入 nanobanana2 默认值。
+        None => GPT_IMAGE_2_MODEL,
+        _ => EDITOR_IMAGE_MODEL_NANOBANANA2,
+    };
+    let aspect_ratio = normalize_editor_generation_aspect_ratio(aspect_ratio);
+    let image_size = normalize_editor_generation_image_size(normalized_model, image_size);
+    let size = editor_generation_size_for_model(normalized_model, aspect_ratio, image_size);
+    let provider_image_size =
+        editor_generation_provider_image_size_for_model(normalized_model, image_size);
+
+    EditorGenerationOptions {
+        model: normalized_model,
+        aspect_ratio,
+        image_size,
+        size,
+        provider_image_size,
+    }
+}
+
+fn normalize_editor_generation_aspect_ratio(aspect_ratio: Option<&str>) -> &'static str {
+    match aspect_ratio
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        Some("2:3") => "2:3",
+        Some("3:2") => "3:2",
+        Some("4:3") => "4:3",
+        Some("9:16") => "9:16",
+        Some("16:9") => "16:9",
+        _ => "1:1",
+    }
+}
+
+fn normalize_editor_generation_image_size(model: &str, image_size: Option<&str>) -> &'static str {
+    match (
+        model,
+        image_size.map(str::trim).filter(|value| !value.is_empty()),
+    ) {
+        (EDITOR_IMAGE_MODEL_NANOBANANA2, Some("0.5K")) => "0.5K",
+        (_, Some("2K")) => "2K",
+        _ => "1K",
+    }
+}
+
+fn editor_generation_size_for_model(model: &str, aspect_ratio: &str, image_size: &str) -> String {
+    if model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+        return match image_size {
+            // 中文注释：VectorEngine 的 nanobanana2 文档要求 0.5K 传入 512。
+            "0.5K" => "512",
+            "2K" => "2048",
+            _ => "1024",
+        }
+        .to_string();
+    }
+
+    match (image_size, aspect_ratio) {
+        ("2K", "1:1") => "2048x2048",
+        // 中文注释：gpt-image-2 文档未列出 2K 竖版，竖版选择回落到文档明确支持的 1K 竖版。
+        ("2K", "2:3") | ("2K", "9:16") => "1024x1536",
+        ("2K", "4:3") => "2048x1536",
+        ("2K", "16:9") | ("2K", "3:2") => "2048x1152",
+        ("1K", "2:3") | ("1K", "9:16") => "1024x1536",
+        ("1K", "4:3") => "1536x1024",
+        ("1K", "3:2") | ("1K", "16:9") => "1536x1024",
+        _ => "1024x1024",
+    }
+    .to_string()
+}
+
+fn editor_generation_provider_image_size_for_model(
+    model: &str,
+    image_size: &'static str,
+) -> &'static str {
+    if model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+        return match image_size {
+            "0.5K" => "512",
+            "2K" => "2K",
+            _ => "1K",
+        };
+    }
+
+    image_size
+}
+
+pub async fn edit_editor_image(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorImageEditRequest>,
+) -> Result<Json<Value>, AppError> {
+    edit_editor_image_for_owner(
+        &state,
+        &request_context,
+        EditorGenerationCaller::from_authenticated(&authenticated),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn edit_editor_image_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    caller: EditorGenerationCaller,
+    payload: EditorImageEditRequest,
+) -> Result<Json<Value>, AppError> {
+    let prompt = payload.prompt.trim().to_string();
+    if prompt.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-image-edit",
+                "message": "修改提示词不能为空",
+            })),
+        );
+    }
+    let reference_image = parse_editor_reference_image(payload.source_image_src.as_str())?;
+
+    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
+        request_context,
+        caller.audit_subject_user_id.clone(),
+        caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+    );
+    let http_client = build_openai_image_http_client(&settings)?;
+    let generated = create_openai_image_edit_with_references(
+        &http_client,
+        &settings,
+        prompt.as_str(),
+        Some("文字、水印、边框、按钮、UI 控件、低清晰度、变形主体"),
+        EDITOR_IMAGE_GENERATION_SIZE,
+        1,
+        &[reference_image],
+        "图片画布修改图片",
+    )
+    .await?;
+    let image = generated.images.into_iter().next().ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "vector-engine",
+            "message": "VectorEngine 未返回图片",
+        }))
+    })?;
+    let (width, height) = image::load_from_memory(image.bytes.as_slice())
+        .map(|image| (image.width(), image.height()))
+        .unwrap_or((1024, 1024));
+    let image_src = format!(
+        "data:{};base64,{}",
+        image.mime_type,
+        BASE64_STANDARD.encode(image.bytes.as_slice())
+    );
+    let generated_asset = persist_editor_generated_asset(
+        state,
+        PersistEditorGeneratedAssetInput {
+            project_id: payload.project_id,
+            owner_user_id: caller.owner_user_id,
+            folder_id: payload.asset_folder_id,
+            label: normalize_optional_string(payload.asset_label)
+                .unwrap_or_else(|| "图片修改结果".to_string()),
+            image_src: image_src.clone(),
+            object_key: None,
+            asset_object_id: None,
+            width,
+            height,
+            prompt: prompt.clone(),
+            actual_prompt: generated.actual_prompt.clone(),
+            model: GPT_IMAGE_2_MODEL.to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: generated.task_id.clone(),
+            source_resource_id: payload.source_resource_id,
+            asset_kind: payload.asset_kind,
+            generation_inputs: payload.generation_inputs,
+        },
+    )
+    .await?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorImageGenerationResponse {
+            image_src,
+            object_key: None,
+            asset_object_id: None,
+            width,
+            height,
+            source_type: "generated",
+            prompt,
+            actual_prompt: generated.actual_prompt,
+            model: GPT_IMAGE_2_MODEL.to_string(),
+            provider: "VectorEngine",
+            task_id: generated.task_id,
+            resource: generated_asset.resource,
+            asset: generated_asset.asset,
+            project: None,
+        },
+    ))
+}
+
+pub async fn generate_editor_icon_spritesheet(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorIconSpritesheetGenerationRequest>,
+) -> Result<Json<Value>, AppError> {
+    generate_editor_icon_spritesheet_for_owner(
+        &state,
+        &request_context,
+        EditorGenerationCaller::from_authenticated(&authenticated),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn generate_editor_icon_spritesheet_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    caller: EditorGenerationCaller,
+    payload: EditorIconSpritesheetGenerationRequest,
+) -> Result<Json<Value>, AppError> {
+    let icon_descriptions = normalize_icon_descriptions(payload.icon_descriptions)?;
+    let reference_image = parse_editor_reference_image(payload.reference_image_src.as_str())
+        .map_err(|error| {
+            error.with_details(json!({
+                "provider": "editor-icon-spritesheet",
+                "field": "referenceImageSrc",
+                "message": "图标素材规范必须是图片 Data URL。",
+            }))
+        })?;
+    let generation_options = normalize_editor_generation_options(
+        payload.model.as_deref(),
+        payload.aspect_ratio.as_deref(),
+        payload.image_size.as_deref(),
+    );
+    let expected_price_mud_points = validate_editor_icon_spritesheet_price(
+        payload.price_mud_points,
+        Some(generation_options.model),
+    )?;
+    let size = generation_options.size.as_str();
+    let prompt = build_editor_icon_spritesheet_prompt(&icon_descriptions);
+
+    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
+        request_context,
+        caller.audit_subject_user_id.clone(),
+        caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+    );
+    let http_client = build_openai_image_http_client(&settings)?;
+    let generated = if generation_options.model == EDITOR_IMAGE_MODEL_NANOBANANA2 {
+        create_openai_nanobanana_generate_content(
+            &http_client,
+            &settings,
+            generation_options.model,
+            prompt.as_str(),
+            None,
+            generation_options.aspect_ratio,
+            generation_options.provider_image_size,
+            &[reference_image],
+            "图片画布生成图标素材 spritesheet",
+        )
+        .await?
+    } else {
+        create_openai_image_edit_with_references_and_model(
+            &http_client,
+            &settings,
+            generation_options.model,
+            prompt.as_str(),
+            None,
+            size,
+            1,
+            &[reference_image],
+            "图片画布生成图标素材 spritesheet",
+        )
+        .await?
+    };
+    let image = generated.images.into_iter().next().ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "vector-engine",
+            "message": "VectorEngine 未返回图标 spritesheet",
+        }))
+    })?;
+    let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
+        .map(|image| (image.width(), image.height()))
+        .unwrap_or((512, 512));
+    let source = DownloadedImage {
+        bytes: image.bytes.clone(),
+        mime_type: image.mime_type.clone(),
+        extension: image.extension.clone(),
+    };
+    let icon_slices = slice_generated_icon_spritesheet_by_connected_components(
+        &source,
+        icon_descriptions.as_slice(),
+    )
+    .map_err(|error| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "editor-icon-spritesheet",
+            "message": error.to_string(),
+        }))
+    })?;
+    let spritesheet_image_src =
+        data_url_from_image_bytes(image.mime_type.as_str(), image.bytes.as_slice());
+    let generation_inputs = payload.generation_inputs.clone();
+    let owner_user_id = caller.owner_user_id;
+    let spritesheet_record = persist_editor_generated_asset(
+        state,
+        PersistEditorGeneratedAssetInput {
+            project_id: payload.project_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            folder_id: payload.asset_folder_id.clone(),
+            label: "图标素材图集".to_string(),
+            image_src: spritesheet_image_src.clone(),
+            object_key: None,
+            asset_object_id: None,
+            width: spritesheet_width,
+            height: spritesheet_height,
+            prompt: prompt.clone(),
+            actual_prompt: generated.actual_prompt.clone(),
+            model: generation_options.model.to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: generated.task_id.clone(),
+            source_resource_id: None,
+            asset_kind: Some("icon-spritesheet".to_string()),
+            generation_inputs: generation_inputs.clone(),
+        },
+    )
+    .await?;
+    let mut icon_image_srcs = Vec::new();
+    for icon in icon_slices {
+        let icon_response = editor_icon_response_from_slice(icon);
+        let icon_record = persist_editor_generated_asset(
+            state,
+            PersistEditorGeneratedAssetInput {
+                project_id: payload.project_id.clone(),
+                owner_user_id: owner_user_id.clone(),
+                folder_id: payload.asset_folder_id.clone(),
+                label: icon_response.name.clone(),
+                image_src: icon_response.image_src.clone(),
+                object_key: None,
+                asset_object_id: None,
+                width: icon_response.width,
+                height: icon_response.height,
+                prompt: prompt.clone(),
+                actual_prompt: generated.actual_prompt.clone(),
+                model: generation_options.model.to_string(),
+                provider: "VectorEngine".to_string(),
+                task_id: generated.task_id.clone(),
+                source_resource_id: None,
+                asset_kind: Some("icon".to_string()),
+                generation_inputs: generation_inputs.clone(),
+            },
+        )
+        .await?;
+        icon_image_srcs.push(EditorIconSpritesheetIconResponse {
+            resource: icon_record.resource,
+            asset: icon_record.asset,
+            ..icon_response
+        });
+    }
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorIconSpritesheetGenerationResponse {
+            spritesheet_image_src,
+            spritesheet_width,
+            spritesheet_height,
+            icon_image_srcs,
+            prompt,
+            actual_prompt: generated.actual_prompt,
+            model: generation_options.model.to_string(),
+            provider: "VectorEngine",
+            task_id: generated.task_id,
+            price_mud_points: expected_price_mud_points,
+            spritesheet_resource: spritesheet_record.resource,
+            spritesheet_asset: spritesheet_record.asset,
+        },
+    ))
+}
+
+pub async fn extract_editor_ui_design_assets(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<EditorUiDesignAssetExtractionRequest>,
+) -> Result<Json<Value>, AppError> {
+    extract_editor_ui_design_assets_for_owner(
+        &state,
+        &request_context,
+        EditorGenerationCaller::from_authenticated(&authenticated),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn extract_editor_ui_design_assets_for_owner(
+    state: &AppState,
+    request_context: &RequestContext,
+    caller: EditorGenerationCaller,
+    payload: EditorUiDesignAssetExtractionRequest,
+) -> Result<Json<Value>, AppError> {
+    let reference_image =
+        parse_editor_reference_image(payload.source_image_src.as_str()).map_err(|error| {
+            error.with_details(json!({
+                "provider": "editor-ui-design-asset-extraction",
+                "field": "sourceImageSrc",
+                "message": "UI设计图必须是图片 Data URL。",
+            }))
+        })?;
+    let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
+        request_context,
+        caller.audit_subject_user_id.clone(),
+        caller
+            .audit_project_id
+            .clone()
+            .or_else(|| payload.project_id.clone()),
+    );
+    let http_client = build_openai_image_http_client(&settings)?;
+    let generated = create_openai_image_edit_with_references_and_model(
+        &http_client,
+        &settings,
+        GPT_IMAGE_2_MODEL,
+        EDITOR_UI_DESIGN_ASSET_EXTRACTION_PROMPT,
+        None,
+        EDITOR_IMAGE_GENERATION_SIZE,
+        1,
+        &[reference_image],
+        "图片画布提取UI设计图素材 spritesheet",
+    )
+    .await?;
+    let image = generated.images.into_iter().next().ok_or_else(|| {
+        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "vector-engine",
+            "message": "VectorEngine 未返回 UI 设计图素材 spritesheet",
+        }))
+    })?;
+    let (spritesheet_width, spritesheet_height) = image::load_from_memory(image.bytes.as_slice())
+        .map(|image| (image.width(), image.height()))
+        .unwrap_or((512, 512));
+    let source = DownloadedImage {
+        bytes: image.bytes.clone(),
+        mime_type: image.mime_type.clone(),
+        extension: image.extension.clone(),
+    };
+    let icon_slices = slice_generated_icon_spritesheet_all_by_connected_components(&source)
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "editor-ui-design-asset-extraction",
+                "message": error.to_string(),
+            }))
+        })?;
+    let spritesheet_image_src =
+        data_url_from_image_bytes(image.mime_type.as_str(), image.bytes.as_slice());
+    let prompt = EDITOR_UI_DESIGN_ASSET_EXTRACTION_PROMPT.to_string();
+    let generation_inputs = payload.generation_inputs.clone();
+    let owner_user_id = caller.owner_user_id;
+    let spritesheet_record = persist_editor_generated_asset(
+        state,
+        PersistEditorGeneratedAssetInput {
+            project_id: payload.project_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            folder_id: payload.asset_folder_id.clone(),
+            label: normalize_optional_string(payload.spritesheet_label)
+                .unwrap_or_else(|| "UI设计图素材图集".to_string()),
+            image_src: spritesheet_image_src.clone(),
+            object_key: None,
+            asset_object_id: None,
+            width: spritesheet_width,
+            height: spritesheet_height,
+            prompt: prompt.clone(),
+            actual_prompt: generated.actual_prompt.clone(),
+            model: GPT_IMAGE_2_MODEL.to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: generated.task_id.clone(),
+            source_resource_id: None,
+            asset_kind: Some("icon-spritesheet".to_string()),
+            generation_inputs: generation_inputs.clone(),
+        },
+    )
+    .await?;
+    let mut icon_image_srcs = Vec::new();
+    for icon in icon_slices {
+        let icon_response = editor_icon_response_from_slice(icon);
+        let icon_record = persist_editor_generated_asset(
+            state,
+            PersistEditorGeneratedAssetInput {
+                project_id: payload.project_id.clone(),
+                owner_user_id: owner_user_id.clone(),
+                folder_id: payload.asset_folder_id.clone(),
+                label: icon_response.name.clone(),
+                image_src: icon_response.image_src.clone(),
+                object_key: None,
+                asset_object_id: None,
+                width: icon_response.width,
+                height: icon_response.height,
+                prompt: prompt.clone(),
+                actual_prompt: generated.actual_prompt.clone(),
+                model: GPT_IMAGE_2_MODEL.to_string(),
+                provider: "VectorEngine".to_string(),
+                task_id: generated.task_id.clone(),
+                source_resource_id: None,
+                asset_kind: Some("icon".to_string()),
+                generation_inputs: generation_inputs.clone(),
+            },
+        )
+        .await?;
+        icon_image_srcs.push(EditorIconSpritesheetIconResponse {
+            resource: icon_record.resource,
+            asset: icon_record.asset,
+            ..icon_response
+        });
+    }
+
+    Ok(json_success_body(
+        Some(&request_context),
+        EditorIconSpritesheetGenerationResponse {
+            spritesheet_image_src,
+            spritesheet_width,
+            spritesheet_height,
+            icon_image_srcs,
+            prompt,
+            actual_prompt: generated.actual_prompt,
+            model: GPT_IMAGE_2_MODEL.to_string(),
+            provider: "VectorEngine",
+            task_id: generated.task_id,
+            price_mud_points: crate::editor_generation_config::editor_image_generation_mud_points(
+                Some("icon"),
+                Some(GPT_IMAGE_2_MODEL),
+            ),
+            spritesheet_resource: spritesheet_record.resource,
+            spritesheet_asset: spritesheet_record.asset,
+        },
+    ))
+}
+
+pub(crate) fn editor_project_payload_from_record(
+    record: EditorProjectRecord,
+) -> EditorProjectPayload {
+    let canvas = editor_canvas_payload_from_record(record.canvas);
+    EditorProjectPayload {
+        project_id: record.project_id,
+        title: record.title,
+        canvas,
+        viewport: EditorCanvasViewportPayload {
+            x: record.viewport.x,
+            y: record.viewport.y,
+            scale: record.viewport.scale,
+        },
+        layers: record.layers,
+        resources: record
+            .resources
+            .into_iter()
+            .map(editor_project_resource_payload_from_record)
+            .collect(),
+        updated_at: record.updated_at,
+    }
+}
+
+fn editor_canvas_payload_from_record(record: EditorCanvasRecord) -> EditorCanvasPayload {
+    EditorCanvasPayload {
+        canvas_id: record.canvas_id,
+        project_id: record.project_id,
+        title: record.title,
+        viewport: EditorCanvasViewportPayload {
+            x: record.viewport.x,
+            y: record.viewport.y,
+            scale: record.viewport.scale,
+        },
+        layers: record.layers,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
+pub(crate) fn editor_project_resource_payload_from_record(
+    record: EditorProjectResourceRecord,
+) -> EditorProjectResourcePayload {
+    EditorProjectResourcePayload {
+        resource_id: record.resource_id,
+        project_id: record.project_id,
+        image_src: record.image_src,
+        object_key: record.object_key,
+        asset_object_id: record.asset_object_id,
+        width: record.width,
+        height: record.height,
+        source_type: record.source_type,
+        prompt: record.prompt,
+        actual_prompt: record.actual_prompt,
+        model: record.model,
+        provider: record.provider,
+        task_id: record.task_id,
+        source_resource_id: record.source_resource_id,
+        asset_kind: record.asset_kind,
+        generation_inputs: record.generation_inputs,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
+pub(crate) fn editor_asset_library_payload_from_record(
+    record: EditorAssetLibraryRecord,
+) -> EditorAssetLibraryPayload {
+    EditorAssetLibraryPayload {
+        folders: record
+            .folders
+            .into_iter()
+            .map(editor_asset_folder_payload_from_record)
+            .collect(),
+        assets: record
+            .assets
+            .into_iter()
+            .map(editor_asset_payload_from_record)
+            .collect(),
+    }
+}
+
+pub(crate) fn editor_asset_folder_payload_from_record(
+    record: EditorAssetFolderRecord,
+) -> EditorAssetFolderPayload {
+    EditorAssetFolderPayload {
+        folder_id: record.folder_id,
+        label: record.label,
+        sort_order: record.sort_order,
+        collapsed: record.collapsed,
+        system_default: record.system_default,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
+pub(crate) fn editor_asset_payload_from_record(record: EditorAssetRecord) -> EditorAssetPayload {
+    EditorAssetPayload {
+        asset_id: record.asset_id,
+        folder_id: record.folder_id,
+        label: record.label,
+        image_src: record.image_src,
+        object_key: record.object_key,
+        asset_object_id: record.asset_object_id,
+        width: record.width,
+        height: record.height,
+        source_type: record.source_type,
+        prompt: record.prompt,
+        actual_prompt: record.actual_prompt,
+        model: record.model,
+        provider: record.provider,
+        task_id: record.task_id,
+        asset_kind: record.asset_kind,
+        generation_inputs: record.generation_inputs,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
+async fn persist_editor_generated_asset(
+    state: &AppState,
+    input: PersistEditorGeneratedAssetInput,
+) -> Result<EditorGeneratedAssetRecord, AppError> {
+    let generation_inputs_json = serialize_editor_asset_metadata(input.generation_inputs.clone())?;
+    let now_micros = current_utc_micros();
+    let resource = if let Some(project_id) = normalize_optional_string(input.project_id.clone()) {
+        let record = state
+            .spacetime_client()
+            .create_editor_project_resource(EditorProjectResourceCreateRecordInput {
+                resource_id: build_prefixed_uuid_id(EDITOR_RESOURCE_ID_PREFIX),
+                project_id,
+                owner_user_id: input.owner_user_id.clone(),
+                asset_object_id: input.asset_object_id.clone(),
+                image_src: input.image_src.clone(),
+                object_key: input.object_key.clone(),
+                width: input.width,
+                height: input.height,
+                source_type: "generated".to_string(),
+                prompt: Some(input.prompt.clone()),
+                actual_prompt: input.actual_prompt.clone(),
+                model: Some(input.model.clone()),
+                provider: Some(input.provider.clone()),
+                task_id: Some(input.task_id.clone()),
+                source_resource_id: normalize_optional_string(input.source_resource_id.clone()),
+                asset_kind: normalize_optional_string(input.asset_kind.clone()),
+                generation_inputs_json: generation_inputs_json.clone(),
+                updated_at_micros: now_micros,
+            })
+            .await
+            .map_err(map_editor_project_error)?;
+        Some(editor_project_resource_payload_from_record(record))
+    } else {
+        None
+    };
+
+    let folder_id =
+        normalize_generated_asset_folder_id(input.folder_id, input.owner_user_id.as_str());
+    let asset = if let Some(folder_id) = folder_id {
+        let record = state
+            .spacetime_client()
+            .create_editor_asset(EditorAssetCreateRecordInput {
+                asset_id: build_prefixed_uuid_id(EDITOR_ASSET_ID_PREFIX),
+                owner_user_id: input.owner_user_id.clone(),
+                folder_id,
+                label: input.label,
+                asset_object_id: input.asset_object_id,
+                image_src: input.image_src,
+                object_key: input.object_key,
+                width: input.width,
+                height: input.height,
+                source_type: "generated".to_string(),
+                prompt: Some(input.prompt),
+                actual_prompt: input.actual_prompt,
+                model: Some(input.model),
+                provider: Some(input.provider),
+                task_id: Some(input.task_id),
+                asset_kind: normalize_optional_string(input.asset_kind),
+                generation_inputs_json,
+                now_micros,
+            })
+            .await
+            .map_err(map_editor_project_error)?;
+        Some(editor_asset_payload_from_record(record))
+    } else {
+        None
+    };
+
+    Ok(EditorGeneratedAssetRecord { resource, asset })
+}
+
+async fn complete_editor_canvas_generation(
+    state: &AppState,
+    owner_user_id: &str,
+    project_id: Option<&str>,
+    completion: Option<&EditorCanvasGenerationCompletionRequest>,
+    resource: Option<&EditorProjectResourcePayload>,
+) -> Result<Option<EditorProjectPayload>, AppError> {
+    let (Some(project_id), Some(completion), Some(resource)) = (project_id, completion, resource)
+    else {
+        return Ok(None);
+    };
+    let project_id = project_id.trim();
+    if project_id.is_empty() || completion.dialog_id.trim().is_empty() {
+        return Ok(None);
+    }
+
+    let project = state
+        .spacetime_client()
+        .get_editor_project(EditorProjectGetRecordInput {
+            project_id: project_id.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+    let completion_result =
+        apply_editor_canvas_generation_completion(project.layers, completion, resource)?;
+    if !completion_result.changed {
+        return Ok(None);
+    }
+    let saved = state
+        .spacetime_client()
+        .save_editor_project_layout(EditorProjectLayoutSaveRecordInput {
+            project_id: project_id.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+            viewport: project.viewport.clone(),
+            layers_json: serialize_editor_layers(completion_result.layers)?,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(Some(editor_project_payload_from_record(saved)))
+}
+
+fn apply_editor_canvas_generation_completion(
+    layers: Value,
+    completion: &EditorCanvasGenerationCompletionRequest,
+    resource: &EditorProjectResourcePayload,
+) -> Result<EditorCanvasGenerationCompletionResult, AppError> {
+    let mut items = match layers {
+        Value::Array(items) => items,
+        _ => Vec::new(),
+    };
+    let Some(placeholder) = items
+        .iter()
+        .find(|item| generation_dialog_item_matches(item, completion.dialog_id.as_str()))
+        .map(|item| {
+            generation_dialog_item_placeholder(item, completion.dialog_id.as_str())
+                .unwrap_or_else(|| completion.placeholder.clone())
+        })
+    else {
+        return Ok(EditorCanvasGenerationCompletionResult {
+            layers: Value::Array(items),
+            changed: false,
+        });
+    };
+    let generated_layer_id = generated_canvas_layer_id(resource.resource_id.as_str());
+    let completed_layer_id = if let Some(existing_layer_id) = items.iter().find_map(|item| {
+        let resource_id = item.get("resourceId").and_then(Value::as_str)?;
+        if resource_id == resource.resource_id {
+            item.get("layerId")
+                .and_then(Value::as_str)
+                .map(str::to_string)
+        } else {
+            None
+        }
+    }) {
+        existing_layer_id
+    } else {
+        let z_index = next_canvas_layer_z_index(&items);
+        items.push(build_generated_canvas_layer_item(
+            completion,
+            &placeholder,
+            resource,
+            generated_layer_id.as_str(),
+            z_index,
+        ));
+        generated_layer_id
+    };
+
+    for item in &mut items {
+        if generation_dialog_item_matches(item, completion.dialog_id.as_str()) {
+            if let Some(dialog) = item.get_mut("dialog").and_then(Value::as_object_mut) {
+                dialog.insert("status".to_string(), json!("idle"));
+                dialog.insert("composerOpen".to_string(), json!(true));
+                dialog.insert("generatedLayerId".to_string(), json!(completed_layer_id));
+                dialog.remove("errorMessage");
+            }
+        }
+    }
+
+    Ok(EditorCanvasGenerationCompletionResult {
+        layers: Value::Array(items),
+        changed: true,
+    })
+}
+
+fn build_generated_canvas_layer_item(
+    completion: &EditorCanvasGenerationCompletionRequest,
+    placeholder: &EditorCanvasGenerationPlaceholderPayload,
+    resource: &EditorProjectResourcePayload,
+    generated_layer_id: &str,
+    z_index: i64,
+) -> Value {
+    let original_width = positive_f64(resource.width as f64, placeholder.original_width);
+    let original_height = positive_f64(resource.height as f64, placeholder.original_height);
+    let width = positive_f64(original_width, placeholder.width);
+    let height = positive_f64(original_height, placeholder.height);
+    let placeholder_width = positive_f64(placeholder.width, width);
+    let placeholder_height = positive_f64(placeholder.height, height);
+    let x = placeholder.x + placeholder_width / 2.0 - width / 2.0;
+    let y = placeholder.y + placeholder_height / 2.0 - height / 2.0;
+    let asset_kind = resource.asset_kind.as_deref();
+
+    json!({
+        "layerId": generated_layer_id,
+        "resourceId": resource.resource_id,
+        "title": completion.title.trim(),
+        "x": x,
+        "y": y,
+        "width": width,
+        "height": height,
+        "originalWidth": original_width,
+        "originalHeight": original_height,
+        "zIndex": z_index,
+        "sourceType": "generated",
+        "mediaType": generated_canvas_media_type(asset_kind),
+        "prompt": resource.prompt,
+        "actualPrompt": resource.actual_prompt,
+        "model": resource.model,
+        "provider": resource.provider,
+        "taskId": resource.task_id,
+        "objectKey": resource.object_key,
+        "assetObjectId": resource.asset_object_id,
+        "sourceResourceId": resource.source_resource_id,
+    })
+}
+
+fn positive_f64(value: f64, fallback: f64) -> f64 {
+    if value.is_finite() && value > 0.0 {
+        value.round().max(1.0)
+    } else if fallback.is_finite() && fallback > 0.0 {
+        fallback.round().max(1.0)
+    } else {
+        1.0
+    }
+}
+
+fn generated_canvas_layer_id(resource_id: &str) -> String {
+    format!("layer-editor-resource-{resource_id}")
+}
+
+fn generated_canvas_media_type(asset_kind: Option<&str>) -> &'static str {
+    match asset_kind {
+        Some("video") => "video",
+        Some("sound-effect") | Some("background-music") => "audio",
+        _ => "image",
+    }
+}
+
+fn next_canvas_layer_z_index(items: &[Value]) -> i64 {
+    items
+        .iter()
+        .filter_map(|item| item.get("zIndex").and_then(Value::as_i64))
+        .max()
+        .unwrap_or(0)
+        + 1
+}
+
+fn generation_dialog_item_matches(item: &Value, dialog_id: &str) -> bool {
+    item.get("itemType").and_then(Value::as_str) == Some("generation-dialog")
+        && item
+            .get("dialog")
+            .and_then(|dialog| dialog.get("id"))
+            .and_then(Value::as_str)
+            .is_some_and(|candidate| candidate == dialog_id)
+}
+
+fn generation_dialog_item_placeholder(
+    item: &Value,
+    dialog_id: &str,
+) -> Option<EditorCanvasGenerationPlaceholderPayload> {
+    if !generation_dialog_item_matches(item, dialog_id) {
+        return None;
+    }
+    serde_json::from_value(
+        item.get("dialog")?
+            .get("placeholder")
+            .cloned()
+            .unwrap_or(Value::Null),
+    )
+    .ok()
+}
+
+fn normalize_generated_asset_folder_id(
+    folder_id: Option<String>,
+    owner_user_id: &str,
+) -> Option<String> {
+    let normalized = normalize_optional_string(folder_id);
+    match normalized.as_deref() {
+        None => None,
+        Some("project") => Some(default_editor_asset_folder_id(owner_user_id)),
+        Some(value) if value.starts_with("folder-") => {
+            Some(default_editor_asset_folder_id(owner_user_id))
+        }
+        Some(_) => normalized,
+    }
+}
+
+fn default_editor_asset_folder_id(owner_user_id: &str) -> String {
+    format!("{owner_user_id}:asset-folder:{EDITOR_ASSET_DEFAULT_FOLDER_ID}")
+}
+
+impl EditorCanvasViewportPayload {
+    pub(crate) fn into_record(self) -> EditorCanvasViewportRecord {
+        EditorCanvasViewportRecord {
+            x: self.x,
+            y: self.y,
+            scale: self.scale,
+        }
+    }
+}
+
+fn current_owner_user_id(authenticated: &AuthenticatedAccessToken) -> String {
+    authenticated.claims().user_id().to_string()
+}
+
+pub(crate) fn serialize_editor_layers(layers: Value) -> Result<String, AppError> {
+    let payload = serde_json::to_string(&layers).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": "editor-project",
+            "message": format!("图层布局无法序列化：{error}"),
+        }))
+    })?;
+    if payload.len() > EDITOR_LAYOUT_MAX_BYTES {
+        return Err(
+            AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE).with_details(json!({
+                "provider": "editor-project",
+                "message": "图层布局过大",
+            })),
+        );
+    }
+    Ok(payload)
+}
+
+pub(crate) fn serialize_editor_asset_metadata(
+    metadata: Option<Value>,
+) -> Result<Option<String>, AppError> {
+    let Some(metadata) = metadata else {
+        return Ok(None);
+    };
+    if metadata.is_null() {
+        return Ok(None);
+    }
+    let payload = serde_json::to_string(&metadata).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": "editor-project",
+            "message": format!("资产元数据无法序列化：{error}"),
+        }))
+    })?;
+    if payload.len() > EDITOR_ASSET_METADATA_MAX_BYTES {
+        return Err(
+            AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE).with_details(json!({
+                "provider": "editor-project",
+                "message": "资产元数据过大",
+            })),
+        );
+    }
+    Ok(Some(payload))
+}
+
+pub(crate) fn normalize_optional_string(value: Option<String>) -> Option<String> {
+    value
+        .map(|item| item.trim().to_string())
+        .filter(|item| !item.is_empty())
+}
+
+pub(crate) fn sanitize_editor_storage_segment(value: &str, fallback: &str) -> String {
+    let normalized = value
+        .trim()
+        .chars()
+        .map(|character| match character {
+            'a'..='z' | '0'..='9' | '-' | '_' => character,
+            'A'..='Z' => character.to_ascii_lowercase(),
+            _ => '-',
+        })
+        .collect::<String>()
+        .split('-')
+        .filter(|part| !part.is_empty())
+        .collect::<Vec<_>>()
+        .join("-");
+    if normalized.is_empty() {
+        fallback.to_string()
+    } else {
+        normalized
+    }
+}
+
+fn normalize_icon_descriptions(descriptions: Vec<String>) -> Result<Vec<String>, AppError> {
+    let normalized = descriptions
+        .into_iter()
+        .map(|description| description.trim().to_string())
+        .filter(|description| !description.is_empty())
+        .take(EDITOR_ICON_DESCRIPTION_LIMIT.saturating_add(1))
+        .collect::<Vec<_>>();
+    if normalized.is_empty() || normalized.len() > EDITOR_ICON_DESCRIPTION_LIMIT {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-icon-spritesheet",
+                "field": "iconDescriptions",
+                "message": "图标素材描述数量必须在 1 到 100 个之间。",
+            })),
+        );
+    }
+    Ok(normalized)
+}
+
+fn editor_icon_spritesheet_bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "editor-icon-spritesheet",
+        "message": message.into(),
+    }))
+}
+
+fn validate_editor_icon_spritesheet_price(
+    price_mud_points: u32,
+    model: Option<&str>,
+) -> Result<u32, AppError> {
+    let expected_price_mud_points =
+        crate::editor_generation_config::editor_image_generation_mud_points(Some("icon"), model);
+    if price_mud_points != expected_price_mud_points {
+        return Err(editor_icon_spritesheet_bad_request(format!(
+            "priceMudPoints 与素材生成计费配置不一致，应为 {expected_price_mud_points}。"
+        )));
+    }
+    Ok(expected_price_mud_points)
+}
+
+fn build_editor_icon_spritesheet_prompt(icon_descriptions: &[String]) -> String {
+    format!(
+        "参考图1的图标素材规范，单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景方便扣除背景，禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：\n\n{}",
+        icon_descriptions.join("、")
+    )
+}
+
+fn build_editor_ui_design_prompt(user_input: &str, has_icon_spec_reference: bool) -> String {
+    let mut prompt = vec![
+        "生成玩法UI原型图".to_string(),
+        format!("【用户输入】{}", user_input.trim()),
+    ];
+    if has_icon_spec_reference {
+        prompt.push("参考图1为图标素材规范，请在UI图标、按钮符号、描边、材质、圆角、阴影和状态层级上严格遵循参考图1的素材规范。".to_string());
+    }
+    prompt.join("\n")
+}
+
+fn build_editor_character_image_prompt(role_setting: &str) -> String {
+    vec![
+        "严格基于图1的角色美术视觉规范指导中的美术风格、角色头身比、角色朝向等特征生成游戏角色形象图。画面中心构图，角色主体完整置于画面中央，禁止镜头透视，禁止特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，禁止生成美术视觉规范、出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。".to_string(),
+        format!("角色设定：{}", role_setting.trim()),
+    ]
+    .join("\n")
+}
+
+fn prepare_editor_character_image_for_response(
+    image: DownloadedOpenAiImage,
+) -> DownloadedOpenAiImage {
+    let Ok(decoded) = image::load_from_memory(image.bytes.as_slice()) else {
+        return image;
+    };
+
+    let processed = apply_generated_asset_sheet_alpha_with_options(
+        decoded,
+        editor_general_cutout_alpha_options(),
+    );
+    let mut encoded = std::io::Cursor::new(Vec::new());
+    if processed
+        .write_to(&mut encoded, image::ImageFormat::Png)
+        .is_err()
+    {
+        return image;
+    }
+
+    DownloadedOpenAiImage {
+        bytes: encoded.into_inner(),
+        mime_type: "image/png".to_string(),
+        extension: "png".to_string(),
+    }
+}
+
+fn editor_general_cutout_alpha_options() -> GeneratedAssetSheetAlphaOptions {
+    GeneratedAssetSheetAlphaOptions {
+        remove_muted_green_screen_background: true,
+        detect_internal_holes: true,
+        internal_hole_min_pixels: 16,
+        ..GeneratedAssetSheetAlphaOptions::green_screen()
+    }
+}
+
+pub(crate) fn data_url_from_image_bytes(mime_type: &str, bytes: &[u8]) -> String {
+    format!(
+        "data:{};base64,{}",
+        mime_type,
+        BASE64_STANDARD.encode(bytes)
+    )
+}
+
+fn editor_icon_response_from_slice(
+    icon: GeneratedAssetSheetConnectedIcon,
+) -> EditorIconSpritesheetIconResponse {
+    EditorIconSpritesheetIconResponse {
+        name: icon.name,
+        image_src: data_url_from_image_bytes("image/png", icon.bytes.as_slice()),
+        width: icon.width,
+        height: icon.height,
+        resource: None,
+        asset: None,
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct EditorGenerationOptions {
+    model: &'static str,
+    aspect_ratio: &'static str,
+    image_size: &'static str,
+    size: String,
+    provider_image_size: &'static str,
+}
+
+pub(crate) struct PersistedEditorGeneratedImage {
+    pub(crate) object_key: String,
+    pub(crate) asset_object_id: String,
+}
+
+pub(crate) async fn persist_editor_generated_image(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: &str,
+    image: &DownloadedOpenAiImage,
+    prompt: &str,
+    actual_prompt: Option<&str>,
+    asset_kind: &str,
+    path_kind: &str,
+    slot: &str,
+) -> Result<PersistedEditorGeneratedImage, AppError> {
+    let oss_client = state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置",
+        }))
+    })?;
+    let prepared =
+        GeneratedImageAssetAdapter::prepare_put_object(GeneratedImageAssetPersistInput {
+            prefix: LegacyAssetPrefix::CharacterDrafts,
+            path_segments: vec![
+                "editor".to_string(),
+                sanitize_editor_storage_segment(path_kind, "generated-images"),
+                sanitize_editor_storage_segment(task_id, "task"),
+            ],
+            file_stem: "image".to_string(),
+            image: GeneratedImageAssetDataUrl {
+                format: normalize_generated_image_asset_mime(image.mime_type.as_str()),
+                bytes: image.bytes.clone(),
+            },
+            access: OssObjectAccess::Private,
+            metadata: GeneratedImageAssetAdapterMetadata {
+                asset_kind: Some(asset_kind.to_string()),
+                owner_user_id: Some(owner_user_id.to_string()),
+                entity_kind: Some(EDITOR_CHARACTER_IMAGE_ENTITY_KIND.to_string()),
+                entity_id: Some(task_id.to_string()),
+                slot: Some(slot.to_string()),
+                provider: Some("vector-engine".to_string()),
+                task_id: Some(task_id.to_string()),
+            },
+            extra_metadata: BTreeMap::from([(
+                "source".to_string(),
+                "image-canvas-editor".to_string(),
+            )]),
+        })
+        .map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                "provider": "generated-image-assets",
+                "message": format!("准备画板角色形象 OSS 上传请求失败：{error:?}"),
+            }))
+        })?;
+    let persisted_mime_type = prepared.format.mime_type.clone();
+    let http_client = reqwest::Client::new();
+    let put_result = oss_client
+        .put_object(&http_client, prepared.request)
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    let head = oss_client
+        .head_object(
+            &http_client,
+            OssHeadObjectRequest {
+                object_key: put_result.object_key.clone(),
+            },
+        )
+        .await
+        .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+    let now_micros = current_utc_micros();
+    let asset_object = state
+        .spacetime_client()
+        .confirm_asset_object(
+            build_asset_object_upsert_input(
+                generate_asset_object_id(now_micros),
+                head.bucket,
+                head.object_key.clone(),
+                AssetObjectAccessPolicy::Private,
+                head.content_type.or(Some(persisted_mime_type)),
+                head.content_length,
+                Some(actual_prompt.unwrap_or(prompt).to_string()),
+                asset_kind.to_string(),
+                Some(task_id.to_string()),
+                Some(owner_user_id.to_string()),
+                None,
+                Some(task_id.to_string()),
+                now_micros,
+            )
+            .map_err(map_editor_asset_field_error)?,
+        )
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "spacetimedb",
+                "message": error.to_string(),
+            }))
+        })?;
+
+    Ok(PersistedEditorGeneratedImage {
+        object_key: head.object_key,
+        asset_object_id: asset_object.asset_object_id,
+    })
+}
+
+pub(crate) fn parse_editor_reference_image(source: &str) -> Result<OpenAiReferenceImage, AppError> {
+    let Some((header, data)) = source.trim().split_once(',') else {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-image-edit",
+                "field": "sourceImageSrc",
+                "message": "修改图片参考图必须是图片 Data URL。",
+            })),
+        );
+    };
+    let Some(mime_type) = header
+        .strip_prefix("data:")
+        .and_then(|value| value.strip_suffix(";base64"))
+        .filter(|value| value.starts_with("image/"))
+    else {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-image-edit",
+                "field": "sourceImageSrc",
+                "message": "修改图片参考图必须是 base64 图片 Data URL。",
+            })),
+        );
+    };
+    let bytes = BASE64_STANDARD.decode(data.trim()).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": "editor-image-edit",
+            "field": "sourceImageSrc",
+            "message": format!("修改图片参考图解码失败：{error}"),
+        }))
+    })?;
+    if bytes.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "editor-image-edit",
+                "field": "sourceImageSrc",
+                "message": "修改图片参考图为空。",
+            })),
+        );
+    }
+    let extension = match mime_type {
+        "image/jpeg" => "jpg",
+        "image/png" => "png",
+        "image/webp" => "webp",
+        _ => "png",
+    };
+    Ok(OpenAiReferenceImage {
+        bytes,
+        mime_type: mime_type.to_string(),
+        file_name: format!("editor-reference.{extension}"),
+    })
+}
+
+pub(crate) fn map_editor_project_error(error: SpacetimeClientError) -> AppError {
+    match error {
+        SpacetimeClientError::Procedure(message) if message.contains("无权") => {
+            AppError::from_status(StatusCode::FORBIDDEN).with_details(json!({
+                "provider": "editor-project",
+                "message": message,
+            }))
+        }
+        SpacetimeClientError::Procedure(message) if message.contains("不存在") => {
+            AppError::from_status(StatusCode::NOT_FOUND).with_details(json!({
+                "provider": "editor-project",
+                "message": message,
+            }))
+        }
+        SpacetimeClientError::Runtime(message) => AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_details(json!({
+                "provider": "editor-project",
+                "message": message,
+            })),
+        other => AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "spacetimedb",
+            "message": other.to_string(),
+        })),
+    }
+}
+
+pub(crate) fn map_editor_asset_field_error(error: AssetObjectFieldError) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "asset-object",
+        "message": error.to_string(),
+    }))
+}
+
+pub(crate) fn current_utc_micros() -> i64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    let duration = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system clock should be after unix epoch");
+    i64::try_from(duration.as_micros()).expect("current unix micros should fit in i64")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn editor_image_generation_size_keeps_quick_edit_canvas_ratio_presets() {
+        assert_eq!(normalize_editor_image_generation_size(None), "1024x1024");
+        assert_eq!(
+            normalize_editor_image_generation_size(Some("1536x1024")),
+            "1536x1024"
+        );
+        assert_eq!(
+            normalize_editor_image_generation_size(Some("1024x1536")),
+            "1024x1536"
+        );
+        assert_eq!(
+            normalize_editor_image_generation_size(Some("2048x1152")),
+            "2048x1152"
+        );
+        assert_eq!(
+            normalize_editor_image_generation_size(Some("640x640")),
+            "640x640"
+        );
+        assert_eq!(
+            normalize_editor_image_generation_size(Some("bad-size")),
+            "1024x1024"
+        );
+    }
+
+    #[test]
+    fn editor_generation_dimensions_follow_model_options() {
+        let default_generation = normalize_editor_generation_options(None, Some("1:1"), Some("1K"));
+        assert_eq!(default_generation.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(default_generation.size, "1024x1024");
+
+        let nanobanana = normalize_editor_generation_options(
+            Some(EDITOR_IMAGE_MODEL_NANOBANANA2),
+            Some("1:1"),
+            Some("0.5K"),
+        );
+        assert_eq!(nanobanana.model, EDITOR_IMAGE_MODEL_NANOBANANA2);
+        assert_eq!(nanobanana.size, "512");
+        assert_eq!(nanobanana.aspect_ratio, "1:1");
+        assert_eq!(nanobanana.image_size, "0.5K");
+        assert_eq!(nanobanana.provider_image_size, "512");
+
+        let nanobanana_alias =
+            normalize_editor_generation_options(Some("nanobanana2"), Some("1:1"), Some("0.5K"));
+        assert_eq!(nanobanana_alias.model, EDITOR_IMAGE_MODEL_NANOBANANA2);
+        assert_eq!(nanobanana_alias.size, "512");
+        assert_eq!(nanobanana_alias.provider_image_size, "512");
+
+        let legacy_nanobanana_alias =
+            normalize_editor_generation_options(Some("nano-banana"), Some("16:9"), Some("2K"));
+        assert_eq!(
+            legacy_nanobanana_alias.model,
+            EDITOR_IMAGE_MODEL_NANOBANANA2
+        );
+        assert_eq!(legacy_nanobanana_alias.size, "2048");
+        assert_eq!(legacy_nanobanana_alias.aspect_ratio, "16:9");
+
+        let gpt = normalize_editor_generation_options(Some("gpt-image-2"), Some("2:3"), Some("1K"));
+        assert_eq!(gpt.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(gpt.size, "1024x1536");
+        assert_eq!(gpt.aspect_ratio, "2:3");
+        assert_eq!(gpt.image_size, "1K");
+        assert_eq!(gpt.provider_image_size, "1K");
+
+        let nanobanana_cover =
+            normalize_editor_generation_options(Some("nanobanana2"), Some("4:3"), Some("1K"));
+        assert_eq!(nanobanana_cover.model, EDITOR_IMAGE_MODEL_NANOBANANA2);
+        assert_eq!(nanobanana_cover.size, "1024");
+        assert_eq!(nanobanana_cover.aspect_ratio, "4:3");
+
+        let gpt_cover =
+            normalize_editor_generation_options(Some("gpt-image-2"), Some("4:3"), Some("1K"));
+        assert_eq!(gpt_cover.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(gpt_cover.size, "1536x1024");
+        assert_eq!(gpt_cover.aspect_ratio, "4:3");
+
+        let gpt_landscape_2k =
+            normalize_editor_generation_options(Some("gpt-image-2"), Some("16:9"), Some("2K"));
+        assert_eq!(gpt_landscape_2k.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(gpt_landscape_2k.size, "2048x1152");
+        assert_eq!(gpt_landscape_2k.aspect_ratio, "16:9");
+        assert_eq!(gpt_landscape_2k.image_size, "2K");
+
+        let gpt_portrait_2k_fallback =
+            normalize_editor_generation_options(Some("gpt-image-2"), Some("9:16"), Some("2K"));
+        assert_eq!(gpt_portrait_2k_fallback.model, GPT_IMAGE_2_MODEL);
+        assert_eq!(gpt_portrait_2k_fallback.size, "1024x1536");
+        assert_eq!(gpt_portrait_2k_fallback.aspect_ratio, "9:16");
+        assert_eq!(gpt_portrait_2k_fallback.image_size, "2K");
+
+        let fallback = normalize_editor_generation_options(
+            Some("unknown-model"),
+            Some("bad-ratio"),
+            Some("bad-size"),
+        );
+        assert_eq!(fallback.model, EDITOR_IMAGE_MODEL_NANOBANANA2);
+        assert_eq!(fallback.size, "1024");
+        assert_eq!(fallback.aspect_ratio, "1:1");
+        assert_eq!(fallback.image_size, "1K");
+        assert_eq!(fallback.provider_image_size, "1K");
+    }
+
+    #[test]
+    fn publication_material_request_size_keeps_workflow_pixels() {
+        let options =
+            normalize_editor_generation_options(Some("gpt-image-2"), Some("4:3"), Some("1K"));
+
+        assert_eq!(
+            resolve_editor_image_request_size(
+                Some("publication-material"),
+                Some("720x540"),
+                true,
+                &options,
+            ),
+            "720x540"
+        );
+        assert_eq!(
+            resolve_editor_image_request_size(Some("generate"), Some("720x540"), true, &options),
+            "1536x1024"
+        );
+    }
+
+    #[test]
+    fn editor_ui_design_prompt_uses_fixed_user_input_block_and_optional_icon_spec() {
+        let prompt = build_editor_ui_design_prompt("二消玩法，主界面和结算弹窗", true);
+
+        assert!(prompt.contains("生成玩法UI原型图"));
+        assert!(prompt.contains("【用户输入】二消玩法，主界面和结算弹窗"));
+        assert!(prompt.contains("参考图1为图标素材规范"));
+
+        let no_reference_prompt = build_editor_ui_design_prompt("只要战斗HUD", false);
+        assert!(!no_reference_prompt.contains("参考图1为图标素材规范"));
+    }
+
+    #[test]
+    fn editor_character_image_prompt_appends_user_role_setting() {
+        let prompt = build_editor_character_image_prompt("菜市场卖菜大妈");
+
+        assert!(prompt.contains("基于图1的角色美术视觉规范指导"));
+        assert!(prompt.contains("生成游戏角色形象图"));
+        assert!(prompt.contains("背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
+        assert!(prompt.contains("禁止镜头透视"));
+        assert!(prompt.contains("角色设定：菜市场卖菜大妈"));
+    }
+
+    #[test]
+    fn editor_character_image_uses_general_cutout_for_green_screen_background() {
+        let width = 12;
+        let height = 12;
+        let mut image = image::RgbaImage::from_pixel(width, height, image::Rgba([0, 255, 0, 255]));
+        for y in 4..8 {
+            for x in 4..8 {
+                image.put_pixel(x, y, image::Rgba([188, 82, 45, 255]));
+            }
+        }
+        let mut encoded = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(&mut encoded, image::ImageFormat::Png)
+            .expect("test image should encode");
+
+        let processed = prepare_editor_character_image_for_response(DownloadedOpenAiImage {
+            bytes: encoded.into_inner(),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        });
+        let decoded = image::load_from_memory(processed.bytes.as_slice())
+            .expect("processed image should decode")
+            .to_rgba8();
+
+        assert_eq!(processed.mime_type, "image/png");
+        assert_eq!(processed.extension, "png");
+        assert_eq!(decoded.get_pixel(0, 0).0[3], 0);
+        assert_eq!(decoded.get_pixel(5, 5).0[3], 255);
+    }
+
+    #[test]
+    fn editor_character_image_general_cutout_removes_muted_green_background() {
+        let width = 20;
+        let height = 20;
+        let mut image =
+            image::RgbaImage::from_pixel(width, height, image::Rgba([59, 131, 67, 255]));
+        for x in 0..width {
+            image.put_pixel(x, 0, image::Rgba([59, 81, 67, 255]));
+            image.put_pixel(x, height - 1, image::Rgba([63, 84, 70, 255]));
+        }
+        for y in 0..height {
+            image.put_pixel(0, y, image::Rgba([59, 81, 67, 255]));
+            image.put_pixel(width - 1, y, image::Rgba([63, 84, 70, 255]));
+        }
+        for y in 7..13 {
+            for x in 7..13 {
+                image.put_pixel(x, y, image::Rgba([188, 82, 45, 255]));
+            }
+        }
+        let mut encoded = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(&mut encoded, image::ImageFormat::Png)
+            .expect("test image should encode");
+
+        let processed = prepare_editor_character_image_for_response(DownloadedOpenAiImage {
+            bytes: encoded.into_inner(),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        });
+        let decoded = image::load_from_memory(processed.bytes.as_slice())
+            .expect("processed image should decode")
+            .to_rgba8();
+
+        assert_eq!(decoded.get_pixel(0, 0).0[3], 0);
+        assert_eq!(decoded.get_pixel(4, 4).0[3], 0);
+        assert_eq!(decoded.get_pixel(10, 10).0[3], 255);
+    }
+
+    #[test]
+    fn editor_character_image_general_cutout_converts_non_png_to_transparent_png() {
+        let width = 12;
+        let height = 12;
+        let mut image =
+            image::RgbImage::from_pixel(width, height, image::Rgb([0_u8, 255_u8, 0_u8]));
+        for y in 4..8 {
+            for x in 4..8 {
+                image.put_pixel(x, y, image::Rgb([188, 82, 45]));
+            }
+        }
+        let mut encoded = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgb8(image)
+            .write_to(&mut encoded, image::ImageFormat::Jpeg)
+            .expect("test image should encode");
+
+        let processed = prepare_editor_character_image_for_response(DownloadedOpenAiImage {
+            bytes: encoded.into_inner(),
+            mime_type: "image/jpeg".to_string(),
+            extension: "jpg".to_string(),
+        });
+        let decoded = image::load_from_memory(processed.bytes.as_slice())
+            .expect("processed image should decode")
+            .to_rgba8();
+
+        assert_eq!(processed.mime_type, "image/png");
+        assert_eq!(processed.extension, "png");
+        assert_eq!(decoded.get_pixel(0, 0).0[3], 0);
+        assert_eq!(decoded.get_pixel(5, 5).0[3], 255);
+    }
+
+    #[test]
+    fn editor_character_image_general_cutout_removes_internal_green_holes() {
+        let width = 16;
+        let height = 16;
+        let mut image = image::RgbaImage::from_pixel(width, height, image::Rgba([0, 255, 0, 255]));
+        for y in 3..13 {
+            for x in 3..13 {
+                image.put_pixel(x, y, image::Rgba([188, 82, 45, 255]));
+            }
+        }
+        for y in 6..10 {
+            for x in 6..10 {
+                image.put_pixel(x, y, image::Rgba([0, 255, 0, 255]));
+            }
+        }
+        let mut encoded = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(&mut encoded, image::ImageFormat::Png)
+            .expect("test image should encode");
+
+        let processed = prepare_editor_character_image_for_response(DownloadedOpenAiImage {
+            bytes: encoded.into_inner(),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        });
+        let decoded = image::load_from_memory(processed.bytes.as_slice())
+            .expect("processed image should decode")
+            .to_rgba8();
+
+        assert_eq!(decoded.get_pixel(0, 0).0[3], 0);
+        assert_eq!(decoded.get_pixel(7, 7).0[3], 0);
+        assert_eq!(decoded.get_pixel(4, 4).0[3], 255);
+    }
+
+    #[test]
+    fn editor_canvas_generation_completion_inserts_result_layer_and_marks_dialog_idle() {
+        let layers = json!([
+            {
+                "layerId": "layer-existing",
+                "resourceId": "resource-existing",
+                "zIndex": 4
+            },
+            {
+                "itemType": "generation-dialog",
+                "layerId": "generation-dialog:dialog-character",
+                "resourceId": "generation-dialog:dialog-character",
+                "dialog": {
+                    "id": "dialog-character",
+                    "mode": "character",
+                    "prompt": "银发游侠",
+                    "status": "generating",
+                    "composerOpen": false,
+                    "errorMessage": "旧错误",
+                    "placeholder": {
+                        "x": 200,
+                        "y": 160,
+                        "width": 420,
+                        "height": 560,
+                        "originalWidth": 1024,
+                        "originalHeight": 1536
+                    }
+                }
+            }
+        ]);
+        let completion = EditorCanvasGenerationCompletionRequest {
+            dialog_id: "dialog-character".to_string(),
+            title: "角色形象 1".to_string(),
+            placeholder: EditorCanvasGenerationPlaceholderPayload {
+                x: 200.0,
+                y: 160.0,
+                width: 420.0,
+                height: 560.0,
+                original_width: 1024.0,
+                original_height: 1536.0,
+            },
+        };
+        let resource = EditorProjectResourcePayload {
+            resource_id: "editor-resource-character".to_string(),
+            project_id: "editor-project-1".to_string(),
+            image_src: "data:image/png;base64,character".to_string(),
+            object_key: Some("generated-character-drafts/editor/character.png".to_string()),
+            asset_object_id: Some("asset-object-1".to_string()),
+            width: 1024,
+            height: 1536,
+            source_type: "generated".to_string(),
+            prompt: Some("银发游侠".to_string()),
+            actual_prompt: Some("实际提示词".to_string()),
+            model: Some("gpt-image-2".to_string()),
+            provider: Some("VectorEngine".to_string()),
+            task_id: Some("task-character".to_string()),
+            source_resource_id: Some("resource-spec".to_string()),
+            asset_kind: Some("character".to_string()),
+            generation_inputs: Some(json!({
+                "fields": [{"title": "角色设定", "value": "银发游侠"}],
+                "references": []
+            })),
+            created_at: "2026-06-21T12:16:22.000Z".to_string(),
+            updated_at: "2026-06-21T12:16:22.000Z".to_string(),
+        };
+
+        let completed = apply_editor_canvas_generation_completion(layers, &completion, &resource)
+            .expect("completion should apply");
+        assert!(completed.changed);
+        let items = completed
+            .layers
+            .as_array()
+            .expect("layers should stay array");
+        let result_layer = items
+            .iter()
+            .find(|item| item["resourceId"] == "editor-resource-character")
+            .expect("result layer should be inserted");
+
+        assert_eq!(
+            result_layer["layerId"],
+            json!("layer-editor-resource-editor-resource-character")
+        );
+        assert_eq!(result_layer["title"], json!("角色形象 1"));
+        assert_eq!(result_layer["x"], json!(-102.0));
+        assert_eq!(result_layer["y"], json!(-328.0));
+        assert_eq!(result_layer["originalWidth"], json!(1024.0));
+        assert_eq!(result_layer["originalHeight"], json!(1536.0));
+        assert_eq!(result_layer["zIndex"], json!(5));
+        assert_eq!(result_layer["mediaType"], json!("image"));
+        assert_eq!(
+            result_layer.get("src"),
+            None,
+            "layout must not embed heavy image payloads"
+        );
+
+        let dialog = items
+            .iter()
+            .find(|item| item["itemType"] == "generation-dialog")
+            .and_then(|item| item.get("dialog"))
+            .expect("dialog should remain");
+        assert_eq!(dialog["status"], json!("idle"));
+        assert_eq!(dialog["composerOpen"], json!(true));
+        assert_eq!(
+            dialog["generatedLayerId"],
+            json!("layer-editor-resource-editor-resource-character")
+        );
+        assert!(dialog.get("errorMessage").is_none());
+    }
+
+    #[test]
+    fn editor_canvas_generation_completion_is_idempotent_for_existing_resource_layer() {
+        let layers = json!([
+            {
+                "layerId": "layer-existing-result",
+                "resourceId": "editor-resource-character",
+                "zIndex": 7
+            },
+            {
+                "itemType": "generation-dialog",
+                "layerId": "generation-dialog:dialog-character",
+                "resourceId": "generation-dialog:dialog-character",
+                "dialog": {
+                    "id": "dialog-character",
+                    "mode": "character",
+                    "prompt": "银发游侠",
+                    "status": "generating",
+                    "composerOpen": false
+                }
+            }
+        ]);
+        let completion = EditorCanvasGenerationCompletionRequest {
+            dialog_id: "dialog-character".to_string(),
+            title: "角色形象 1".to_string(),
+            placeholder: EditorCanvasGenerationPlaceholderPayload {
+                x: 0.0,
+                y: 0.0,
+                width: 1.0,
+                height: 1.0,
+                original_width: 1.0,
+                original_height: 1.0,
+            },
+        };
+        let resource = EditorProjectResourcePayload {
+            resource_id: "editor-resource-character".to_string(),
+            project_id: "editor-project-1".to_string(),
+            image_src: "data:image/png;base64,character".to_string(),
+            object_key: None,
+            asset_object_id: None,
+            width: 1024,
+            height: 1024,
+            source_type: "generated".to_string(),
+            prompt: Some("银发游侠".to_string()),
+            actual_prompt: None,
+            model: Some("gpt-image-2".to_string()),
+            provider: Some("VectorEngine".to_string()),
+            task_id: Some("task-character".to_string()),
+            source_resource_id: None,
+            asset_kind: Some("character".to_string()),
+            generation_inputs: None,
+            created_at: "2026-06-21T12:16:22.000Z".to_string(),
+            updated_at: "2026-06-21T12:16:22.000Z".to_string(),
+        };
+
+        let completed = apply_editor_canvas_generation_completion(layers, &completion, &resource)
+            .expect("completion should apply");
+        assert!(completed.changed);
+        let items = completed
+            .layers
+            .as_array()
+            .expect("layers should stay array");
+
+        assert_eq!(
+            items
+                .iter()
+                .filter(|item| item["resourceId"] == "editor-resource-character")
+                .count(),
+            1
+        );
+        let dialog = items
+            .iter()
+            .find(|item| item["itemType"] == "generation-dialog")
+            .and_then(|item| item.get("dialog"))
+            .expect("dialog should remain");
+        assert_eq!(dialog["generatedLayerId"], json!("layer-existing-result"));
+    }
+
+    #[test]
+    fn editor_canvas_generation_completion_uses_latest_layout_placeholder() {
+        let layers = json!([
+            {
+                "itemType": "generation-dialog",
+                "layerId": "generation-dialog:dialog-character",
+                "resourceId": "generation-dialog:dialog-character",
+                "dialog": {
+                    "id": "dialog-character",
+                    "mode": "character",
+                    "prompt": "银发游侠",
+                    "status": "generating",
+                    "composerOpen": false,
+                    "placeholder": {
+                        "x": 500,
+                        "y": 400,
+                        "width": 420,
+                        "height": 560,
+                        "originalWidth": 1024,
+                        "originalHeight": 1536
+                    }
+                }
+            }
+        ]);
+        let completion = EditorCanvasGenerationCompletionRequest {
+            dialog_id: "dialog-character".to_string(),
+            title: "角色形象 1".to_string(),
+            placeholder: EditorCanvasGenerationPlaceholderPayload {
+                x: 0.0,
+                y: 0.0,
+                width: 1.0,
+                height: 1.0,
+                original_width: 1.0,
+                original_height: 1.0,
+            },
+        };
+        let resource = EditorProjectResourcePayload {
+            resource_id: "editor-resource-character".to_string(),
+            project_id: "editor-project-1".to_string(),
+            image_src: "data:image/png;base64,character".to_string(),
+            object_key: None,
+            asset_object_id: None,
+            width: 1024,
+            height: 1536,
+            source_type: "generated".to_string(),
+            prompt: Some("银发游侠".to_string()),
+            actual_prompt: None,
+            model: Some("gpt-image-2".to_string()),
+            provider: Some("VectorEngine".to_string()),
+            task_id: Some("task-character".to_string()),
+            source_resource_id: None,
+            asset_kind: Some("character".to_string()),
+            generation_inputs: None,
+            created_at: "2026-06-21T12:16:22.000Z".to_string(),
+            updated_at: "2026-06-21T12:16:22.000Z".to_string(),
+        };
+
+        let completed = apply_editor_canvas_generation_completion(layers, &completion, &resource)
+            .expect("completion should apply");
+        let result_layer = completed
+            .layers
+            .as_array()
+            .expect("layers should stay array")
+            .iter()
+            .find(|item| item["resourceId"] == "editor-resource-character")
+            .expect("result layer should be inserted");
+
+        assert_eq!(result_layer["x"], json!(198.0));
+        assert_eq!(result_layer["y"], json!(-88.0));
+    }
+
+    #[test]
+    fn editor_canvas_generation_completion_skips_when_dialog_was_removed() {
+        let layers = json!([
+            {
+                "layerId": "layer-existing",
+                "resourceId": "resource-existing",
+                "zIndex": 4
+            }
+        ]);
+        let completion = EditorCanvasGenerationCompletionRequest {
+            dialog_id: "dialog-character".to_string(),
+            title: "角色形象 1".to_string(),
+            placeholder: EditorCanvasGenerationPlaceholderPayload {
+                x: 200.0,
+                y: 160.0,
+                width: 420.0,
+                height: 560.0,
+                original_width: 1024.0,
+                original_height: 1536.0,
+            },
+        };
+        let resource = EditorProjectResourcePayload {
+            resource_id: "editor-resource-character".to_string(),
+            project_id: "editor-project-1".to_string(),
+            image_src: "data:image/png;base64,character".to_string(),
+            object_key: None,
+            asset_object_id: None,
+            width: 1024,
+            height: 1536,
+            source_type: "generated".to_string(),
+            prompt: Some("银发游侠".to_string()),
+            actual_prompt: None,
+            model: Some("gpt-image-2".to_string()),
+            provider: Some("VectorEngine".to_string()),
+            task_id: Some("task-character".to_string()),
+            source_resource_id: None,
+            asset_kind: Some("character".to_string()),
+            generation_inputs: None,
+            created_at: "2026-06-21T12:16:22.000Z".to_string(),
+            updated_at: "2026-06-21T12:16:22.000Z".to_string(),
+        };
+
+        let completed = apply_editor_canvas_generation_completion(layers, &completion, &resource)
+            .expect("completion should be ignored");
+
+        assert!(!completed.changed);
+        assert_eq!(
+            completed.layers,
+            json!([
+                {
+                    "layerId": "layer-existing",
+                    "resourceId": "resource-existing",
+                    "zIndex": 4
+                }
+            ])
+        );
+    }
+
+    #[test]
+    fn editor_icon_spritesheet_prompt_uses_ordered_descriptions_and_size_tiers() {
+        let descriptions = vec![
+            "返回按钮".to_string(),
+            "设置按钮".to_string(),
+            "下一关按钮".to_string(),
+        ];
+        let prompt = build_editor_icon_spritesheet_prompt(&descriptions);
+
+        assert!(prompt.contains("参考图1的图标素材规范"));
+        assert!(prompt.contains("单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景方便扣除背景"));
+        assert!(prompt.contains("返回按钮、设置按钮、下一关按钮"));
+    }
+
+    #[test]
+    fn editor_ui_design_asset_extraction_prompt_is_fixed() {
+        assert_eq!(
+            EDITOR_UI_DESIGN_ASSET_EXTRACTION_PROMPT,
+            "提取画面中的所有独立并整理成spritesheet"
+        );
+    }
+
+    #[test]
+    fn editor_icon_description_validation_filters_empty_and_rejects_more_than_limit() {
+        let descriptions = normalize_icon_descriptions(vec![
+            " 返回按钮 ".to_string(),
+            " ".to_string(),
+            "设置按钮".to_string(),
+        ])
+        .expect("valid descriptions should pass");
+        assert_eq!(descriptions, vec!["返回按钮", "设置按钮"]);
+
+        let too_many = (0..101)
+            .map(|index| format!("图标{index}"))
+            .collect::<Vec<_>>();
+        assert!(normalize_icon_descriptions(too_many).is_err());
+    }
+
+    #[test]
+    fn editor_icon_spritesheet_request_price_uses_generation_config() {
+        assert_eq!(
+            validate_editor_icon_spritesheet_price(12, Some("gemini-3.1-flash-image-preview"))
+                .unwrap(),
+            12
+        );
+        assert_eq!(
+            validate_editor_icon_spritesheet_price(20, Some("gpt-image-2")).unwrap(),
+            20
+        );
+        let error = validate_editor_icon_spritesheet_price(5, Some("gpt-image-2"))
+            .expect_err("wrong icon spritesheet price should fail");
+        assert!(error.body_text().contains("priceMudPoints"));
+        let response = EditorIconSpritesheetGenerationResponse {
+            spritesheet_image_src: "data:image/png;base64,sheet".to_string(),
+            spritesheet_width: 512,
+            spritesheet_height: 512,
+            icon_image_srcs: vec![EditorIconSpritesheetIconResponse {
+                name: "返回按钮".to_string(),
+                image_src: "data:image/png;base64,back".to_string(),
+                width: 128,
+                height: 128,
+                resource: None,
+                asset: None,
+            }],
+            prompt: "图标 prompt".to_string(),
+            actual_prompt: Some("图标 prompt".to_string()),
+            model: "gemini-3.1-flash-image-preview".to_string(),
+            provider: "VectorEngine",
+            task_id: "task-icons".to_string(),
+            price_mud_points: crate::editor_generation_config::editor_image_generation_mud_points(
+                Some("icon"),
+                None,
+            ),
+            spritesheet_resource: None,
+            spritesheet_asset: None,
+        };
+        let payload = serde_json::to_value(response).expect("response should serialize");
+
+        assert_eq!(payload["priceMudPoints"], json!(12));
+    }
+
+    #[test]
+    fn generated_asset_folder_id_normalizes_project_and_legacy_local_folder() {
+        assert_eq!(
+            normalize_generated_asset_folder_id(Some("project".to_string()), "user-1"),
+            Some("user-1:asset-folder:project".to_string())
+        );
+        assert_eq!(
+            normalize_generated_asset_folder_id(Some(" folder-temporary ".to_string()), "user-1"),
+            Some("user-1:asset-folder:project".to_string())
+        );
+        assert_eq!(
+            normalize_generated_asset_folder_id(Some("folder-real".to_string()), "user-1"),
+            Some("user-1:asset-folder:project".to_string())
+        );
+        assert_eq!(
+            normalize_generated_asset_folder_id(
+                Some("user-1:asset-folder:project".to_string()),
+                "user-1",
+            ),
+            Some("user-1:asset-folder:project".to_string())
+        );
+        assert_eq!(normalize_generated_asset_folder_id(None, "user-1"), None);
+    }
+}
diff --git a/server-rs/crates/api-server/src/external_api_auth.rs b/server-rs/crates/api-server/src/external_api_auth.rs
new file mode 100644
index 000000000..e7ee85b29
--- /dev/null
+++ b/server-rs/crates/api-server/src/external_api_auth.rs
@@ -0,0 +1,91 @@
+use axum::{
+    extract::{Request, State},
+    http::{HeaderMap, StatusCode, header::AUTHORIZATION},
+    middleware::Next,
+    response::Response,
+};
+use spacetime_client::ExternalApiKeyAuthenticateRecordInput;
+use tracing::warn;
+
+use crate::{
+    editor_project::current_utc_micros,
+    external_api_keys::{hash_external_api_key, map_external_api_key_error},
+    http_error::AppError,
+    request_context::RequestContext,
+    state::AppState,
+};
+
+#[derive(Clone, Debug)]
+pub struct ExternalApiPrincipal {
+    owner_user_id: String,
+    key_id: String,
+    scopes: Vec<String>,
+}
+
+impl ExternalApiPrincipal {
+    pub fn owner_user_id(&self) -> &str {
+        self.owner_user_id.as_str()
+    }
+
+    pub fn key_id(&self) -> &str {
+        self.key_id.as_str()
+    }
+
+    pub fn has_scope(&self, scope: &str) -> bool {
+        self.scopes.iter().any(|item| item == scope)
+    }
+}
+
+pub async fn require_external_api_key(
+    State(state): State<AppState>,
+    mut request: Request,
+    next: Next,
+) -> Result<Response, AppError> {
+    let request_id = request
+        .extensions()
+        .get::<RequestContext>()
+        .map(|context| context.request_id().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+    let raw_key = extract_external_api_bearer(request.headers())?;
+    let key = state
+        .spacetime_client()
+        .authenticate_external_api_key(ExternalApiKeyAuthenticateRecordInput {
+            key_hash: hash_external_api_key(raw_key.as_str()),
+            used_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| {
+            warn!(
+                %request_id,
+                error = %error,
+                "外部 API Key 校验失败"
+            );
+            map_external_api_key_error(error)
+        })?;
+    let principal = ExternalApiPrincipal {
+        owner_user_id: key.owner_user_id,
+        key_id: key.key_id,
+        scopes: key.scopes,
+    };
+    request.extensions_mut().insert(principal.clone());
+
+    let mut response = next.run(request).await;
+    response.extensions_mut().insert(principal);
+    Ok(response)
+}
+
+fn extract_external_api_bearer(headers: &HeaderMap) -> Result<String, AppError> {
+    let authorization = headers
+        .get(AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .ok_or_else(|| AppError::from_status(StatusCode::UNAUTHORIZED))?;
+
+    authorization
+        .strip_prefix("Bearer ")
+        .or_else(|| authorization.strip_prefix("bearer "))
+        .map(str::trim)
+        .filter(|token| !token.is_empty())
+        .map(ToOwned::to_owned)
+        .ok_or_else(|| AppError::from_status(StatusCode::UNAUTHORIZED))
+}
diff --git a/server-rs/crates/api-server/src/external_api_keys.rs b/server-rs/crates/api-server/src/external_api_keys.rs
new file mode 100644
index 000000000..7d620c6a6
--- /dev/null
+++ b/server-rs/crates/api-server/src/external_api_keys.rs
@@ -0,0 +1,248 @@
+use axum::{
+    Json,
+    extract::{Extension, Path, State},
+    http::StatusCode,
+};
+use platform_auth::hash_refresh_session_token;
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_kernel::{build_prefixed_uuid_id, new_uuid_simple_string};
+use spacetime_client::{
+    ExternalApiKeyCreateRecordInput, ExternalApiKeyRecord, ExternalApiKeyRevokeRecordInput,
+    SpacetimeClientError,
+};
+
+use crate::{
+    api_response::json_success_body, auth::AuthenticatedAccessToken,
+    editor_project::current_utc_micros, http_error::AppError, request_context::RequestContext,
+    state::AppState,
+};
+
+const EXTERNAL_API_KEY_ID_PREFIX: &str = "external-api-key-";
+const EXTERNAL_API_KEY_SECRET_PREFIX: &str = "tnr_sk_";
+const EXTERNAL_API_KEY_PREFIX_VISIBLE_CHARS: usize = 18;
+const EXTERNAL_API_KEY_SCOPES: [&str; 4] = [
+    "editor:project",
+    "editor:canvas",
+    "editor:image-generate",
+    "editor:asset",
+];
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalApiKeyCreateRequest {
+    name: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalApiKeyPayload {
+    key_id: String,
+    name: String,
+    key_prefix: String,
+    scopes: Vec<String>,
+    created_at: String,
+    last_used_at: Option<String>,
+    revoked_at: Option<String>,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalApiKeyCreateResponse {
+    api_key: String,
+    key: ExternalApiKeyPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalApiKeyListResponse {
+    keys: Vec<ExternalApiKeyPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalApiKeyResponse {
+    key: ExternalApiKeyPayload,
+}
+
+pub async fn list_external_api_keys(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let keys = state
+        .spacetime_client()
+        .list_external_api_keys(authenticated.claims().user_id().to_string())
+        .await
+        .map_err(map_external_api_key_error)?
+        .into_iter()
+        .map(external_api_key_payload_from_record)
+        .collect();
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalApiKeyListResponse { keys },
+    ))
+}
+
+pub async fn create_external_api_key(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<ExternalApiKeyCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    let raw_key = generate_external_api_key_secret();
+    let key_prefix = external_api_key_prefix(raw_key.as_str());
+    let key = state
+        .spacetime_client()
+        .create_external_api_key(ExternalApiKeyCreateRecordInput {
+            key_id: build_prefixed_uuid_id(EXTERNAL_API_KEY_ID_PREFIX),
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            name: payload
+                .name
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty())
+                .unwrap_or_else(|| "外部 API Key".to_string()),
+            key_prefix,
+            key_hash: hash_external_api_key(raw_key.as_str()),
+            scopes: default_external_api_key_scopes(),
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_external_api_key_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalApiKeyCreateResponse {
+            api_key: raw_key,
+            key: external_api_key_payload_from_record(key),
+        },
+    ))
+}
+
+pub async fn revoke_external_api_key(
+    State(state): State<AppState>,
+    Path(key_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, AppError> {
+    let key = state
+        .spacetime_client()
+        .revoke_external_api_key(ExternalApiKeyRevokeRecordInput {
+            key_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            revoked_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_external_api_key_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalApiKeyResponse {
+            key: external_api_key_payload_from_record(key),
+        },
+    ))
+}
+
+pub(crate) fn hash_external_api_key(raw_key: &str) -> String {
+    hash_refresh_session_token(raw_key)
+}
+
+pub(crate) fn default_external_api_key_scopes() -> Vec<String> {
+    EXTERNAL_API_KEY_SCOPES
+        .iter()
+        .map(|scope| (*scope).to_string())
+        .collect()
+}
+
+fn generate_external_api_key_secret() -> String {
+    format!(
+        "{EXTERNAL_API_KEY_SECRET_PREFIX}{}.{}",
+        new_uuid_simple_string(),
+        new_uuid_simple_string()
+    )
+}
+
+fn external_api_key_prefix(raw_key: &str) -> String {
+    raw_key
+        .chars()
+        .take(EXTERNAL_API_KEY_PREFIX_VISIBLE_CHARS)
+        .collect()
+}
+
+fn external_api_key_payload_from_record(record: ExternalApiKeyRecord) -> ExternalApiKeyPayload {
+    ExternalApiKeyPayload {
+        key_id: record.key_id,
+        name: record.name,
+        key_prefix: record.key_prefix,
+        scopes: record.scopes,
+        created_at: record.created_at,
+        last_used_at: record.last_used_at,
+        revoked_at: record.revoked_at,
+        updated_at: record.updated_at,
+    }
+}
+
+pub(crate) fn map_external_api_key_error(error: SpacetimeClientError) -> AppError {
+    match error {
+        SpacetimeClientError::Procedure(message)
+            if message.contains("不存在") || message.contains("已失效") =>
+        {
+            AppError::from_status(StatusCode::UNAUTHORIZED).with_details(json!({
+                "provider": "external-api-key",
+                "message": message,
+            }))
+        }
+        SpacetimeClientError::Procedure(message) if message.contains("无权") => {
+            AppError::from_status(StatusCode::FORBIDDEN).with_details(json!({
+                "provider": "external-api-key",
+                "message": message,
+            }))
+        }
+        SpacetimeClientError::Runtime(message) | SpacetimeClientError::Procedure(message) => {
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "external-api-key",
+                "message": message,
+            }))
+        }
+        other => AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+            "provider": "spacetimedb",
+            "message": other.to_string(),
+        })),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn generated_external_api_key_uses_public_prefix_only_for_display() {
+        let raw_key = generate_external_api_key_secret();
+        let key_prefix = external_api_key_prefix(raw_key.as_str());
+
+        assert!(raw_key.starts_with(EXTERNAL_API_KEY_SECRET_PREFIX));
+        assert_eq!(
+            key_prefix.chars().count(),
+            EXTERNAL_API_KEY_PREFIX_VISIBLE_CHARS
+        );
+        assert!(raw_key.starts_with(key_prefix.as_str()));
+        assert_ne!(hash_external_api_key(raw_key.as_str()), raw_key);
+    }
+
+    #[test]
+    fn default_external_api_key_scopes_cover_editor_openapi_v1() {
+        let scopes = default_external_api_key_scopes();
+
+        assert_eq!(
+            scopes,
+            vec![
+                "editor:project".to_string(),
+                "editor:canvas".to_string(),
+                "editor:image-generate".to_string(),
+                "editor:asset".to_string(),
+            ]
+        );
+    }
+}
diff --git a/server-rs/crates/api-server/src/external_assets_api.rs b/server-rs/crates/api-server/src/external_assets_api.rs
new file mode 100644
index 000000000..bca6422fe
--- /dev/null
+++ b/server-rs/crates/api-server/src/external_assets_api.rs
@@ -0,0 +1,75 @@
+use axum::{
+    Json,
+    extract::{Extension, Query, State},
+    http::StatusCode,
+};
+use serde_json::{Value, json};
+use shared_contracts::assets::{
+    ConfirmAssetObjectRequest, CreateDirectUploadTicketRequest, GetReadUrlQuery,
+};
+
+use crate::{
+    assets::{
+        confirm_asset_object_for_owner, create_direct_upload_ticket_for_owner,
+        get_asset_read_url_with_query,
+    },
+    external_api_auth::ExternalApiPrincipal,
+    http_error::AppError,
+    request_context::RequestContext,
+    state::AppState,
+};
+
+const SCOPE_EDITOR_ASSET: &str = "editor:asset";
+const EXTERNAL_ASSET_PROVIDER: &str = "external-assets-api";
+
+pub async fn create_external_direct_upload_ticket(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<CreateDirectUploadTicketRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    create_direct_upload_ticket_for_owner(
+        &state,
+        &request_context,
+        principal.owner_user_id(),
+        payload,
+    )
+    .await
+}
+
+pub async fn confirm_external_asset_object(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(mut payload): Json<ConfirmAssetObjectRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    payload.owner_user_id = Some(principal.owner_user_id().to_string());
+    confirm_asset_object_for_owner(&state, &request_context, principal.owner_user_id(), payload)
+        .await
+}
+
+pub async fn get_external_asset_read_url(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Query(query): Query<GetReadUrlQuery>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    get_asset_read_url_with_query(&state, &request_context, query).await
+}
+
+fn require_scope(principal: &ExternalApiPrincipal, scope: &str) -> Result<(), AppError> {
+    if principal.has_scope(scope) {
+        return Ok(());
+    }
+    Err(
+        AppError::from_status(StatusCode::FORBIDDEN).with_details(json!({
+            "provider": EXTERNAL_ASSET_PROVIDER,
+            "keyId": principal.key_id(),
+            "scope": scope,
+            "message": "API Key 缺少所需权限",
+        })),
+    )
+}
diff --git a/server-rs/crates/api-server/src/external_editor_api.rs b/server-rs/crates/api-server/src/external_editor_api.rs
new file mode 100644
index 000000000..fd3cba2e4
--- /dev/null
+++ b/server-rs/crates/api-server/src/external_editor_api.rs
@@ -0,0 +1,897 @@
+use axum::{
+    Json,
+    extract::{Extension, Path, State, rejection::JsonRejection},
+    http::{StatusCode, header::CONTENT_TYPE},
+    response::{IntoResponse, Response},
+};
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use shared_kernel::build_prefixed_uuid_id;
+use spacetime_client::{
+    EditorAssetCreateRecordInput, EditorAssetDeleteRecordInput, EditorAssetFolderCreateRecordInput,
+    EditorAssetFolderDeleteRecordInput, EditorAssetFolderUpdateRecordInput,
+    EditorAssetUpdateRecordInput, EditorProjectCreateRecordInput, EditorProjectDeleteRecordInput,
+    EditorProjectGetRecordInput, EditorProjectLayoutSaveRecordInput,
+    EditorProjectRenameRecordInput, EditorProjectResourceCreateRecordInput,
+};
+
+use crate::{
+    api_response::json_success_body,
+    character_animation_assets::{
+        generate_editor_character_animation_for_owner, generate_editor_video_for_owner,
+    },
+    editor_project::{
+        EDITOR_ASSET_FOLDER_ID_PREFIX, EDITOR_ASSET_ID_PREFIX, EDITOR_PROJECT_DEFAULT_TITLE,
+        EDITOR_PROJECT_ID_PREFIX, EDITOR_RESOURCE_ID_PREFIX, EditorAssetFolderPayload,
+        EditorAssetLibraryPayload, EditorAssetPayload, EditorCanvasViewportPayload,
+        EditorGenerationCaller, EditorIconSpritesheetGenerationRequest, EditorImageEditRequest,
+        EditorImageGenerationRequest, EditorProjectPayload, EditorProjectResourcePayload,
+        EditorUiDesignAssetExtractionRequest, current_utc_micros, edit_editor_image_for_owner,
+        editor_asset_folder_payload_from_record, editor_asset_library_payload_from_record,
+        editor_asset_payload_from_record, editor_project_payload_from_record,
+        editor_project_resource_payload_from_record, extract_editor_ui_design_assets_for_owner,
+        generate_editor_icon_spritesheet_for_owner, generate_editor_image_for_owner,
+        map_editor_project_error, normalize_optional_string, serialize_editor_asset_metadata,
+        serialize_editor_layers,
+    },
+    external_api_auth::ExternalApiPrincipal,
+    http_error::AppError,
+    request_context::RequestContext,
+    state::AppState,
+    vector_engine_audio_generation::{
+        generate_editor_background_music_for_owner, generate_editor_sound_effect_for_owner,
+    },
+};
+
+const EXTERNAL_EDITOR_PROVIDER: &str = "external-editor-api";
+const SCOPE_EDITOR_PROJECT: &str = "editor:project";
+const SCOPE_EDITOR_CANVAS: &str = "editor:canvas";
+const SCOPE_EDITOR_IMAGE_GENERATE: &str = "editor:image-generate";
+const SCOPE_EDITOR_ASSET: &str = "editor:asset";
+const OPENAPI_JSON: &str =
+    include_str!("../../../../docs/openapi/genarrative-external-v1.openapi.json");
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectCreateRequest {
+    title: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorCanvasSaveRequest {
+    viewport: EditorCanvasViewportPayload,
+    layers: Value,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectRenameRequest {
+    title: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetFolderCreateRequest {
+    label: String,
+    sort_order: Option<u32>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetFolderUpdateRequest {
+    label: Option<String>,
+    collapsed: Option<bool>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetCreateRequest {
+    folder_id: String,
+    label: String,
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectResourceCreateRequest {
+    image_src: String,
+    object_key: Option<String>,
+    asset_object_id: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    source_resource_id: Option<String>,
+    asset_kind: Option<String>,
+    generation_inputs: Option<Value>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetUpdateRequest {
+    label: Option<String>,
+    folder_id: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectResponse {
+    project: EditorProjectPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectRecentResponse {
+    project: Option<EditorProjectPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectListResponse {
+    projects: Vec<EditorProjectPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectDeleteResponse {
+    deleted_project_id: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetLibraryResponse {
+    library: EditorAssetLibraryPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetFolderResponse {
+    folder: EditorAssetFolderPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetFolderDeleteResponse {
+    library: EditorAssetLibraryPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorAssetResponse {
+    asset: EditorAssetPayload,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ExternalEditorProjectResourceResponse {
+    resource: EditorProjectResourcePayload,
+}
+
+pub async fn openapi_json() -> Response {
+    (
+        [(CONTENT_TYPE, "application/json; charset=utf-8")],
+        OPENAPI_JSON,
+    )
+        .into_response()
+}
+
+pub async fn create_external_editor_project(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorProjectCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let project = state
+        .spacetime_client()
+        .create_editor_project(EditorProjectCreateRecordInput {
+            project_id: build_prefixed_uuid_id(EDITOR_PROJECT_ID_PREFIX),
+            owner_user_id: principal.owner_user_id().to_string(),
+            title: normalize_project_title(payload.title),
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn list_external_editor_projects(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let projects = state
+        .spacetime_client()
+        .list_editor_projects(principal.owner_user_id().to_string())
+        .await
+        .map_err(map_editor_project_error)?
+        .into_iter()
+        .map(editor_project_payload_from_record)
+        .collect();
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectListResponse { projects },
+    ))
+}
+
+pub async fn load_recent_external_editor_project(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let project = state
+        .spacetime_client()
+        .get_recent_editor_project(principal.owner_user_id().to_string())
+        .await
+        .map_err(map_editor_project_error)?
+        .map(editor_project_payload_from_record);
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectRecentResponse { project },
+    ))
+}
+
+pub async fn get_external_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let project = state
+        .spacetime_client()
+        .get_editor_project(EditorProjectGetRecordInput {
+            project_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn rename_external_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorProjectRenameRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let project = state
+        .spacetime_client()
+        .rename_editor_project(EditorProjectRenameRecordInput {
+            project_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            title: payload.title,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn delete_external_editor_project(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_PROJECT)?;
+    let deleted_project_id = state
+        .spacetime_client()
+        .delete_editor_project(EditorProjectDeleteRecordInput {
+            project_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectDeleteResponse { deleted_project_id },
+    ))
+}
+
+pub async fn save_external_editor_canvas(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorCanvasSaveRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_CANVAS)?;
+    let project = state
+        .spacetime_client()
+        .save_editor_project_layout(EditorProjectLayoutSaveRecordInput {
+            project_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            viewport: payload.viewport.into_record(),
+            layers_json: serialize_editor_layers(payload.layers)?,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectResponse {
+            project: editor_project_payload_from_record(project),
+        },
+    ))
+}
+
+pub async fn get_external_editor_asset_library(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let library = state
+        .spacetime_client()
+        .get_editor_asset_library(principal.owner_user_id().to_string(), current_utc_micros())
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetLibraryResponse {
+            library: editor_asset_library_payload_from_record(library),
+        },
+    ))
+}
+
+pub async fn create_external_editor_asset_folder(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorAssetFolderCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let folder = state
+        .spacetime_client()
+        .create_editor_asset_folder(EditorAssetFolderCreateRecordInput {
+            folder_id: build_prefixed_uuid_id(EDITOR_ASSET_FOLDER_ID_PREFIX),
+            owner_user_id: principal.owner_user_id().to_string(),
+            label: payload.label,
+            sort_order: payload.sort_order.unwrap_or(100),
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetFolderResponse {
+            folder: editor_asset_folder_payload_from_record(folder),
+        },
+    ))
+}
+
+pub async fn update_external_editor_asset_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorAssetFolderUpdateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let folder = state
+        .spacetime_client()
+        .update_editor_asset_folder(EditorAssetFolderUpdateRecordInput {
+            folder_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            label: normalize_optional_string(payload.label),
+            collapsed: payload.collapsed,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetFolderResponse {
+            folder: editor_asset_folder_payload_from_record(folder),
+        },
+    ))
+}
+
+pub async fn delete_external_editor_asset_folder(
+    State(state): State<AppState>,
+    Path(folder_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let library = state
+        .spacetime_client()
+        .delete_editor_asset_folder(EditorAssetFolderDeleteRecordInput {
+            folder_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetFolderDeleteResponse {
+            library: editor_asset_library_payload_from_record(library),
+        },
+    ))
+}
+
+pub async fn create_external_editor_asset(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorAssetCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let generation_inputs_json =
+        serialize_editor_asset_metadata(payload.generation_inputs.clone())?;
+    let asset = state
+        .spacetime_client()
+        .create_editor_asset(EditorAssetCreateRecordInput {
+            asset_id: build_prefixed_uuid_id(EDITOR_ASSET_ID_PREFIX),
+            owner_user_id: principal.owner_user_id().to_string(),
+            folder_id: payload.folder_id,
+            label: payload.label,
+            asset_object_id: normalize_optional_string(payload.asset_object_id),
+            image_src: payload.image_src,
+            object_key: normalize_optional_string(payload.object_key),
+            width: payload.width,
+            height: payload.height,
+            source_type: payload.source_type,
+            prompt: normalize_optional_string(payload.prompt),
+            actual_prompt: normalize_optional_string(payload.actual_prompt),
+            model: normalize_optional_string(payload.model),
+            provider: normalize_optional_string(payload.provider),
+            task_id: normalize_optional_string(payload.task_id),
+            asset_kind: normalize_optional_string(payload.asset_kind),
+            generation_inputs_json,
+            now_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn update_external_editor_asset(
+    State(state): State<AppState>,
+    Path(asset_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorAssetUpdateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let asset = state
+        .spacetime_client()
+        .update_editor_asset(EditorAssetUpdateRecordInput {
+            asset_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            label: normalize_optional_string(payload.label),
+            folder_id: normalize_optional_string(payload.folder_id),
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn delete_external_editor_asset(
+    State(state): State<AppState>,
+    Path(asset_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let asset = state
+        .spacetime_client()
+        .delete_editor_asset(EditorAssetDeleteRecordInput {
+            asset_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorAssetResponse {
+            asset: editor_asset_payload_from_record(asset),
+        },
+    ))
+}
+
+pub async fn create_external_editor_project_resource(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<ExternalEditorProjectResourceCreateRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_ASSET)?;
+    let generation_inputs_json =
+        serialize_editor_asset_metadata(payload.generation_inputs.clone())?;
+    let resource = state
+        .spacetime_client()
+        .create_editor_project_resource(EditorProjectResourceCreateRecordInput {
+            resource_id: build_prefixed_uuid_id(EDITOR_RESOURCE_ID_PREFIX),
+            project_id,
+            owner_user_id: principal.owner_user_id().to_string(),
+            asset_object_id: normalize_optional_string(payload.asset_object_id),
+            image_src: payload.image_src,
+            object_key: normalize_optional_string(payload.object_key),
+            width: payload.width,
+            height: payload.height,
+            source_type: payload.source_type,
+            prompt: normalize_optional_string(payload.prompt),
+            actual_prompt: normalize_optional_string(payload.actual_prompt),
+            model: normalize_optional_string(payload.model),
+            provider: normalize_optional_string(payload.provider),
+            task_id: normalize_optional_string(payload.task_id),
+            source_resource_id: normalize_optional_string(payload.source_resource_id),
+            asset_kind: normalize_optional_string(payload.asset_kind),
+            generation_inputs_json,
+            updated_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(map_editor_project_error)?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        ExternalEditorProjectResourceResponse {
+            resource: editor_project_resource_payload_from_record(resource),
+        },
+    ))
+}
+
+pub async fn generate_external_editor_image(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<EditorImageGenerationRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_image_for_owner(
+        &state,
+        &request_context,
+        editor_generation_caller(&principal, payload.project_id.clone()),
+        payload,
+    )
+    .await
+}
+
+pub async fn edit_external_editor_image(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<EditorImageEditRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    edit_editor_image_for_owner(
+        &state,
+        &request_context,
+        editor_generation_caller(&principal, payload.project_id.clone()),
+        payload,
+    )
+    .await
+}
+
+pub async fn generate_external_editor_icon_spritesheet(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<EditorIconSpritesheetGenerationRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_icon_spritesheet_for_owner(
+        &state,
+        &request_context,
+        editor_generation_caller(&principal, payload.project_id.clone()),
+        payload,
+    )
+    .await
+}
+
+pub async fn extract_external_editor_ui_design_assets(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    Json(payload): Json<EditorUiDesignAssetExtractionRequest>,
+) -> Result<Json<Value>, AppError> {
+    require_scope(&principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    extract_editor_ui_design_assets_for_owner(
+        &state,
+        &request_context,
+        editor_generation_caller(&principal, payload.project_id.clone()),
+        payload,
+    )
+    .await
+}
+
+pub async fn generate_external_editor_character_animation(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    payload: Result<
+        Json<shared_contracts::assets::EditorCharacterAnimationGenerateRequest>,
+        JsonRejection,
+    >,
+) -> Result<Json<Value>, Response> {
+    require_scope_response(&request_context, &principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_character_animation_for_owner(
+        state,
+        request_context,
+        principal.owner_user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+pub async fn generate_external_editor_video(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    payload: Result<Json<shared_contracts::assets::EditorVideoGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    require_scope_response(&request_context, &principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_video_for_owner(
+        state,
+        request_context,
+        principal.owner_user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+pub async fn generate_external_editor_sound_effect(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    payload: Result<
+        Json<shared_contracts::assets::EditorSoundEffectGenerateRequest>,
+        JsonRejection,
+    >,
+) -> Result<Json<Value>, Response> {
+    require_scope_response(&request_context, &principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_sound_effect_for_owner(
+        state,
+        request_context,
+        principal.owner_user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+pub async fn generate_external_editor_background_music(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(principal): Extension<ExternalApiPrincipal>,
+    payload: Result<
+        Json<shared_contracts::assets::EditorBackgroundMusicGenerateRequest>,
+        JsonRejection,
+    >,
+) -> Result<Json<Value>, Response> {
+    require_scope_response(&request_context, &principal, SCOPE_EDITOR_IMAGE_GENERATE)?;
+    generate_editor_background_music_for_owner(
+        state,
+        request_context,
+        principal.owner_user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+fn editor_generation_caller(
+    principal: &ExternalApiPrincipal,
+    project_id: Option<String>,
+) -> EditorGenerationCaller {
+    EditorGenerationCaller {
+        owner_user_id: principal.owner_user_id().to_string(),
+        audit_subject_user_id: Some(principal.owner_user_id().to_string()),
+        audit_project_id: normalize_optional_string(project_id),
+    }
+}
+
+fn require_scope(principal: &ExternalApiPrincipal, scope: &str) -> Result<(), AppError> {
+    if principal.has_scope(scope) {
+        return Ok(());
+    }
+    Err(
+        AppError::from_status(StatusCode::FORBIDDEN).with_details(json!({
+            "provider": EXTERNAL_EDITOR_PROVIDER,
+            "keyId": principal.key_id(),
+            "scope": scope,
+            "message": "API Key 缺少所需权限",
+        })),
+    )
+}
+
+fn require_scope_response(
+    request_context: &RequestContext,
+    principal: &ExternalApiPrincipal,
+    scope: &str,
+) -> Result<(), Response> {
+    require_scope(principal, scope)
+        .map_err(|error| error.into_response_with_context(Some(request_context)))
+}
+
+fn normalize_project_title(title: Option<String>) -> String {
+    title
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(|| EDITOR_PROJECT_DEFAULT_TITLE.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn exported_openapi_json_contains_external_editor_routes_and_security() {
+        let parsed: Value = serde_json::from_str(OPENAPI_JSON).expect("openapi json should parse");
+
+        assert_eq!(parsed["openapi"], "3.1.0");
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/projects")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/assets/direct-upload-tickets")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/assets/objects/confirm")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/assets/read-url")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]["/api/external/v1/editor/projects"]
+                .get("get")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]["/api/external/v1/editor/projects"]
+                .get("post")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/projects/recent")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]["/api/external/v1/editor/projects/{projectId}"]
+                .get("delete")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/projects/{projectId}/metadata")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/images/generations")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/images/edits")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/icon-spritesheets/generations")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/ui-designs/assets/extractions")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/videos/generations")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/audios/sound-effects/generations")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/audios/background-music/generations")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/assets/library")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/projects/{projectId}/resources")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/assets/folders")
+                .is_some()
+        );
+        assert!(
+            parsed["paths"]
+                .get("/api/external/v1/editor/assets/{assetId}")
+                .is_some()
+        );
+        assert!(parsed["paths"].get("/api/profile/api-keys").is_none());
+        assert!(
+            parsed["components"]["securitySchemes"]
+                .get("UserAccessToken")
+                .is_none()
+        );
+        assert_eq!(
+            parsed["components"]["securitySchemes"]["ExternalApiKey"]["scheme"],
+            "bearer"
+        );
+    }
+}
diff --git a/server-rs/crates/api-server/src/jump_hop.rs b/server-rs/crates/api-server/src/jump_hop.rs
index 8200eab26..bdd44c586 100644
--- a/server-rs/crates/api-server/src/jump_hop.rs
+++ b/server-rs/crates/api-server/src/jump_hop.rs
@@ -1037,7 +1037,7 @@ fn build_jump_hop_back_button_prompt(theme_text: &str) -> String {
     let theme_text = normalize_jump_hop_generation_theme_text(theme_text);
 
     format!(
-        "生成跳一跳运行态左上角返回按钮的独立透明素材。主题关键词严格只使用“{theme_text}”，按钮的底色、材质、描边和轻微装饰跟随该主题，但必须仍然是清晰可识别的游戏 UI 返回按钮。\n按钮必须是单个标准圆形图标，圆心居中，主体视觉尺寸占画布约72%-82%，外沿有一圈干净描边，内部只有一个居中的向左箭头；不要写“返回”文字，不要数字、Logo、水印、按钮外标签或额外 UI 面板。\n允许在圆形底色里做很轻的主题材质包装，例如水果主题可用果皮色和果肉色、森林主题可用叶片色和木质描边、未来主题可用金属边和发光内环；但不要把按钮画成主题物体本身，不要继承复杂花纹、浮雕边、异形外框、贴纸堆叠或徽章装饰。\n尺寸1:1，输出绿色背景主体图，背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影；按钮主体边缘干净，后续由服务端扣除绿色背景。按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请使用偏深、偏黄或偏蓝的主题绿色，并用高对比箭头颜色区分。\nEnglish guardrail: one standalone circular mobile game back button asset only, theme-styled colors/materials from \"{theme_text}\", centered left arrow only, no text, no logo, no extra UI, no complex badge, no object silhouette, solid #00FF00 green-screen background for later alpha removal."
+        "生成跳一跳运行态左上角返回按钮的独立透明素材。主题关键词严格只使用“{theme_text}”，按钮的底色、材质、描边和轻微装饰跟随该主题，但必须仍然是清晰可识别的游戏 UI 返回按钮。\n按钮必须是单个标准圆形图标，圆心居中，主体视觉尺寸占画布约72%-82%，外沿有一圈干净描边，内部只有一个居中的向左箭头；不要写“返回”文字，不要数字、Logo、水印、按钮外标签或额外 UI 面板。\n允许在圆形底色里做很轻的主题材质包装，例如水果主题可用果皮色和果肉色、森林主题可用叶片色和木质描边、未来主题可用金属边和发光内环；但不要把按钮画成主题物体本身，不要继承复杂花纹、浮雕边、异形外框、贴纸堆叠或徽章装饰。\n尺寸1:1，输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，背景必须严格使用 #00FF00 / RGB(0,255,0) 且平整无纹理、无渐变、无阴影；按钮主体边缘干净，后续由服务端扣除绿色背景。按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请使用偏深、偏黄或偏蓝的主题绿色，并用高对比箭头颜色区分。\nEnglish guardrail: one standalone circular mobile game back button asset only, theme-styled colors/materials from \"{theme_text}\", centered left arrow only, no text, no logo, no extra UI, no complex badge, no object silhouette, solid #00FF00 / RGB(0,255,0) green-screen background for later alpha removal."
     )
 }
 
@@ -2081,7 +2081,7 @@ mod tests {
         assert!(!prompt.contains("25格造型要混排"));
         assert!(!prompt.contains("no simple circles"));
         assert!(!prompt.contains("no simple squares"));
-        assert!(!prompt.contains("纯绿色绿幕"));
+        assert!(!prompt.contains("单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕"));
         assert!(!prompt.contains("#00FF00"));
         assert!(!prompt.contains("isolated top-down"));
         assert!(!prompt.contains("按5行*5列"));
@@ -2128,10 +2128,10 @@ mod tests {
         assert!(prompt.contains("单个标准圆形图标"));
         assert!(prompt.contains("内部只有一个居中的向左箭头"));
         assert!(prompt.contains("不要写“返回”文字"));
-        assert!(prompt.contains("背景必须是单一纯绿色 #00FF00"));
+        assert!(prompt.contains("背景必须严格使用 #00FF00 / RGB(0,255,0)"));
         assert!(prompt.contains("后续由服务端扣除绿色背景"));
         assert!(prompt.contains("one standalone circular mobile game back button asset only"));
-        assert!(prompt.contains("solid #00FF00 green-screen background"));
+        assert!(prompt.contains("solid #00FF00 / RGB(0,255,0) green-screen background"));
     }
 
     #[test]
diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs
index 90af7ba2f..e9da1150a 100644
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -36,10 +36,16 @@ mod custom_world_asset_prompts;
 mod custom_world_foundation_draft;
 mod custom_world_result_prompts;
 mod custom_world_rpg_draft_prompts;
+mod editor_generation_config;
+mod editor_project;
 mod edutainment_baby_drawing;
 mod edutainment_baby_object;
 mod error_middleware;
 mod external_api_audit;
+mod external_api_auth;
+mod external_api_keys;
+mod external_assets_api;
+mod external_editor_api;
 mod external_generation;
 mod external_generation_worker;
 mod external_generation_worker_controller;
diff --git a/server-rs/crates/api-server/src/match3d/item_assets.rs b/server-rs/crates/api-server/src/match3d/item_assets.rs
index 5de20f2ed..fddcb3a3b 100644
--- a/server-rs/crates/api-server/src/match3d/item_assets.rs
+++ b/server-rs/crates/api-server/src/match3d/item_assets.rs
@@ -1483,7 +1483,7 @@ pub(super) fn build_match3d_material_sheet_prompt(
 }
 
 pub(super) fn build_match3d_item_spritesheet_prompt() -> String {
-    "固定生成10行*10列spritesheet图，统一纯绿色绿幕背景（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。素材间距严格均匀分布，任意两个素材间距相同，物品来自参考图中画面中心容器中的2D素材。每一行包含两种物品，每种物品的五个不同形态。物品素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色物品只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。严禁出现两种高相似度的物品".to_string()
+    "固定生成10行*10列spritesheet图，统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景，背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。素材间距严格均匀分布，任意两个素材间距相同，物品来自参考图中画面中心容器中的2D素材。每一行包含两种物品，每种物品的五个不同形态。物品素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色物品只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。严禁出现两种高相似度的物品".to_string()
 }
 
 fn match3d_material_sheet_special_prompt() -> String {
diff --git a/server-rs/crates/api-server/src/match3d/tests.rs b/server-rs/crates/api-server/src/match3d/tests.rs
index 3f753d5a8..8e139f854 100644
--- a/server-rs/crates/api-server/src/match3d/tests.rs
+++ b/server-rs/crates/api-server/src/match3d/tests.rs
@@ -914,7 +914,7 @@ fn match3d_material_sheet_prompt_requires_uniform_ten_by_ten_layout() {
     assert!(prompt.contains("每一行包含两种物品"));
     assert!(prompt.contains("每种物品的五个不同形态"));
     assert!(prompt.contains("绿幕背景"));
-    assert!(prompt.contains("#00FF00"));
+    assert!(prompt.contains("#00FF00 / RGB(0,255,0)"));
     assert!(prompt.contains("严禁出现两种高相似度的物品"));
 }
 
diff --git a/server-rs/crates/api-server/src/match3d/works.rs b/server-rs/crates/api-server/src/match3d/works.rs
index 05e5f35aa..fe00e7f64 100644
--- a/server-rs/crates/api-server/src/match3d/works.rs
+++ b/server-rs/crates/api-server/src/match3d/works.rs
@@ -714,7 +714,7 @@ pub(super) fn build_match3d_level_scene_generation_prompt(config: &Match3DConfig
 }
 
 pub(super) fn build_match3d_ui_spritesheet_prompt() -> String {
-    "提取画面中的UI元素，将返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮的顺序从上到下从左到右整理成纯绿色绿幕背景spritesheet。背景必须是统一纯绿色绿幕（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。UI 素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。".to_string()
+    "提取画面中的UI元素，将返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮的顺序从上到下从左到右整理成单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景spritesheet。背景必须是统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。UI 素材自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。".to_string()
 }
 
 pub(super) fn build_match3d_background_from_scene_prompt() -> String {
diff --git a/server-rs/crates/api-server/src/modules.rs b/server-rs/crates/api-server/src/modules.rs
index f79ec8340..ee51d7682 100644
--- a/server-rs/crates/api-server/src/modules.rs
+++ b/server-rs/crates/api-server/src/modules.rs
@@ -4,7 +4,9 @@ pub mod auth;
 pub mod bark_battle;
 pub mod big_fish;
 pub mod custom_world;
+pub mod editor_project;
 pub mod edutainment;
+pub mod external_api;
 pub mod external_generation;
 pub mod health;
 pub mod internal;
diff --git a/server-rs/crates/api-server/src/modules/editor_project.rs b/server-rs/crates/api-server/src/modules/editor_project.rs
new file mode 100644
index 000000000..08204463c
--- /dev/null
+++ b/server-rs/crates/api-server/src/modules/editor_project.rs
@@ -0,0 +1,148 @@
+use axum::{
+    Router,
+    extract::DefaultBodyLimit,
+    middleware,
+    routing::{get, patch, post},
+};
+
+use crate::{
+    auth::require_bearer_auth,
+    editor_project::{
+        create_editor_asset, create_editor_asset_folder, create_editor_project,
+        create_editor_project_resource, delete_editor_asset, delete_editor_asset_folder,
+        delete_editor_project, edit_editor_image, extract_editor_ui_design_assets,
+        generate_editor_icon_spritesheet, generate_editor_image, get_editor_asset_library,
+        get_editor_project, list_editor_projects, load_recent_editor_project,
+        rename_editor_project, save_editor_project_layout, update_editor_asset,
+        update_editor_asset_folder,
+    },
+    state::AppState,
+};
+
+const EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
+
+pub fn router(state: AppState) -> Router<AppState> {
+    Router::new()
+        .route(
+            "/api/editor/projects/recent",
+            get(load_recent_editor_project).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/projects",
+            get(list_editor_projects)
+                .post(create_editor_project)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/projects/{project_id}",
+            get(get_editor_project)
+                .patch(save_editor_project_layout)
+                .delete(delete_editor_project)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/projects/{project_id}/metadata",
+            patch(rename_editor_project).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/projects/{project_id}/resources",
+            post(create_editor_project_resource).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/assets/library",
+            get(get_editor_asset_library).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/assets/folders",
+            post(create_editor_asset_folder).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/assets/folders/{folder_id}",
+            patch(update_editor_asset_folder)
+                .delete(delete_editor_asset_folder)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/assets",
+            post(create_editor_asset).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/assets/{asset_id}",
+            patch(update_editor_asset)
+                .delete(delete_editor_asset)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/images/generations",
+            post(generate_editor_image)
+                .layer(DefaultBodyLimit::max(
+                    // 中文注释：图片画布生图仍兼容参考图 Data URL 入参，宣发素材提交前会压缩，后端保留有限兜底。
+                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/images/edits",
+            post(edit_editor_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/icon-spritesheets/generations",
+            post(generate_editor_icon_spritesheet)
+                // 中文注释：图标规范参考图会以 Data URL 提交，需避免默认 2MB body limit 在 handler 前拦截。
+                .layer(DefaultBodyLimit::max(
+                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/ui-designs/assets/extractions",
+            post(extract_editor_ui_design_assets)
+                // 中文注释：UI 设计图提取素材复用图片 Data URL 入参，需兼容较大的画板生成图。
+                .layer(DefaultBodyLimit::max(
+                    EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+}
diff --git a/server-rs/crates/api-server/src/modules/external_api.rs b/server-rs/crates/api-server/src/modules/external_api.rs
new file mode 100644
index 000000000..3841ffb25
--- /dev/null
+++ b/server-rs/crates/api-server/src/modules/external_api.rs
@@ -0,0 +1,220 @@
+use axum::{
+    Router,
+    extract::DefaultBodyLimit,
+    middleware,
+    routing::{get, patch, post},
+};
+
+use crate::{
+    external_api_auth::require_external_api_key,
+    external_assets_api::{
+        confirm_external_asset_object, create_external_direct_upload_ticket,
+        get_external_asset_read_url,
+    },
+    external_editor_api::{
+        create_external_editor_asset, create_external_editor_asset_folder,
+        create_external_editor_project, create_external_editor_project_resource,
+        delete_external_editor_asset, delete_external_editor_asset_folder,
+        delete_external_editor_project, edit_external_editor_image,
+        extract_external_editor_ui_design_assets, generate_external_editor_background_music,
+        generate_external_editor_character_animation, generate_external_editor_icon_spritesheet,
+        generate_external_editor_image, generate_external_editor_sound_effect,
+        generate_external_editor_video, get_external_editor_asset_library,
+        get_external_editor_project, list_external_editor_projects,
+        load_recent_external_editor_project, openapi_json, rename_external_editor_project,
+        save_external_editor_canvas, update_external_editor_asset,
+        update_external_editor_asset_folder,
+    },
+    state::AppState,
+};
+
+const EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
+const EXTERNAL_EDITOR_VIDEO_BODY_LIMIT_BYTES: usize = 64 * 1024 * 1024;
+
+pub fn router(state: AppState) -> Router<AppState> {
+    Router::new()
+        .route("/api/external/v1/openapi.json", get(openapi_json))
+        .route(
+            "/api/external/v1/assets/direct-upload-tickets",
+            post(create_external_direct_upload_ticket).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/assets/objects/confirm",
+            post(confirm_external_asset_object).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/assets/read-url",
+            get(get_external_asset_read_url).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/projects",
+            get(list_external_editor_projects)
+                .post(create_external_editor_project)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/projects/recent",
+            get(load_recent_external_editor_project).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/projects/{project_id}",
+            get(get_external_editor_project)
+                .delete(delete_external_editor_project)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/projects/{project_id}/metadata",
+            patch(rename_external_editor_project).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/projects/{project_id}/canvas",
+            patch(save_external_editor_canvas).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/projects/{project_id}/resources",
+            post(create_external_editor_project_resource).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_external_api_key),
+            ),
+        )
+        .route(
+            "/api/external/v1/editor/assets/library",
+            get(get_external_editor_asset_library).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/assets/folders",
+            post(create_external_editor_asset_folder).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/assets/folders/{folder_id}",
+            patch(update_external_editor_asset_folder)
+                .delete(delete_external_editor_asset_folder)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/assets",
+            post(create_external_editor_asset).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_external_api_key,
+            )),
+        )
+        .route(
+            "/api/external/v1/editor/assets/{asset_id}",
+            patch(update_external_editor_asset)
+                .delete(delete_external_editor_asset)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/images/generations",
+            post(generate_external_editor_image)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/images/edits",
+            post(edit_external_editor_image)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/icon-spritesheets/generations",
+            post(generate_external_editor_icon_spritesheet)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/ui-designs/assets/extractions",
+            post(extract_external_editor_ui_design_assets)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/character-animations/generations",
+            post(generate_external_editor_character_animation)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_IMAGE_REFERENCE_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/videos/generations",
+            post(generate_external_editor_video)
+                .layer(DefaultBodyLimit::max(
+                    EXTERNAL_EDITOR_VIDEO_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_external_api_key,
+                )),
+        )
+        .route(
+            "/api/external/v1/editor/audios/sound-effects/generations",
+            post(generate_external_editor_sound_effect).route_layer(
+                middleware::from_fn_with_state(state.clone(), require_external_api_key),
+            ),
+        )
+        .route(
+            "/api/external/v1/editor/audios/background-music/generations",
+            post(generate_external_editor_background_music).route_layer(
+                middleware::from_fn_with_state(state, require_external_api_key),
+            ),
+        )
+}
diff --git a/server-rs/crates/api-server/src/modules/play_flow.rs b/server-rs/crates/api-server/src/modules/play_flow.rs
index be85f2605..c90d06150 100644
--- a/server-rs/crates/api-server/src/modules/play_flow.rs
+++ b/server-rs/crates/api-server/src/modules/play_flow.rs
@@ -16,7 +16,8 @@ use crate::{
     assets::get_asset_history,
     auth::require_bearer_auth,
     character_animation_assets::{
-        generate_character_animation, get_character_animation_job, get_character_workflow_cache,
+        generate_character_animation, generate_editor_character_animation, generate_editor_video,
+        get_character_animation_job, get_character_workflow_cache,
         import_character_animation_video, list_character_animation_templates,
         publish_character_animation, put_role_asset_workflow, resolve_role_asset_workflow,
         save_character_workflow_cache,
@@ -45,9 +46,14 @@ use crate::{
     runtime_save::{list_profile_save_archives, resume_profile_save_archive},
     runtime_settings::{get_runtime_settings, put_runtime_settings},
     state::AppState,
+    vector_engine_audio_generation::{
+        generate_editor_background_music, generate_editor_sound_effect,
+    },
 };
 
 const HYPER3D_IMAGE_TO_MODEL_BODY_LIMIT_BYTES: usize = 56 * 1024 * 1024;
+const EDITOR_CHARACTER_ANIMATION_BODY_LIMIT_BYTES: usize = 12 * 1024 * 1024;
+const EDITOR_VIDEO_BODY_LIMIT_BYTES: usize = 64 * 1024 * 1024;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct PlayFlowDomainAdapter {
@@ -452,6 +458,36 @@ fn play_flow_support_router(state: AppState) -> Router<AppState> {
             "/api/assets/character-animation/generate",
             post(generate_character_animation),
         )
+        .route(
+            "/api/editor/character-animations/generations",
+            post(generate_editor_character_animation).layer(DefaultBodyLimit::max(
+                // 中文注释：画板角色动画首版仍兼容角色图 Data URL 入参，避免大于 Axum 默认 2MB 的角色图在 handler 前被拦截。
+                EDITOR_CHARACTER_ANIMATION_BODY_LIMIT_BYTES,
+            )),
+        )
+        .route(
+            "/api/editor/videos/generations",
+            post(generate_editor_video)
+                .layer(DefaultBodyLimit::max(EDITOR_VIDEO_BODY_LIMIT_BYTES))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/editor/audios/sound-effects/generations",
+            post(generate_editor_sound_effect).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/editor/audios/background-music/generations",
+            post(generate_editor_background_music).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/assets/character-animation/jobs/{task_id}",
             get(get_character_animation_job),
diff --git a/server-rs/crates/api-server/src/modules/profile.rs b/server-rs/crates/api-server/src/modules/profile.rs
index 54b17f8b9..58b7c1b9e 100644
--- a/server-rs/crates/api-server/src/modules/profile.rs
+++ b/server-rs/crates/api-server/src/modules/profile.rs
@@ -1,10 +1,11 @@
 use axum::{
     Router, middleware,
-    routing::{get, patch, post},
+    routing::{delete, get, patch, post},
 };
 
 use crate::{
     auth::require_bearer_auth,
+    external_api_keys::{create_external_api_key, list_external_api_keys, revoke_external_api_key},
     profile_identity::update_profile_identity,
     runtime_profile::{
         claim_profile_task_reward, confirm_wechat_profile_recharge_order,
@@ -32,6 +33,22 @@ pub fn router(state: AppState) -> Router<AppState> {
                 require_bearer_auth,
             )),
         )
+        .route(
+            "/api/profile/api-keys",
+            get(list_external_api_keys)
+                .post(create_external_api_key)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route(
+            "/api/profile/api-keys/{key_id}",
+            delete(revoke_external_api_key).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/profile/wallet-ledger",
             get(get_profile_wallet_ledger).route_layer(middleware::from_fn_with_state(
diff --git a/server-rs/crates/api-server/src/openai_image_generation.rs b/server-rs/crates/api-server/src/openai_image_generation.rs
index ea026cf69..6e461dfd0 100644
--- a/server-rs/crates/api-server/src/openai_image_generation.rs
+++ b/server-rs/crates/api-server/src/openai_image_generation.rs
@@ -3,7 +3,9 @@ use platform_image::{
     DownloadedImage, GeneratedImages, PlatformImageError, PlatformImageStatusHint, ReferenceImage,
     VECTOR_ENGINE_PROVIDER, VectorEngineImageSettings, build_vector_engine_image_http_client,
     create_vector_engine_image_edit, create_vector_engine_image_edit_with_references,
-    create_vector_engine_image_generation,
+    create_vector_engine_image_edit_with_references_and_model,
+    create_vector_engine_image_generation, create_vector_engine_image_generation_with_model,
+    create_vector_engine_nanobanana_generate_content,
 };
 #[cfg(test)]
 use platform_image::{
@@ -159,6 +161,94 @@ pub(crate) async fn create_openai_image_generation(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn create_openai_image_generation_with_model(
+    http_client: &reqwest::Client,
+    settings: &OpenAiImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    size: &str,
+    candidate_count: u32,
+    reference_images: &[String],
+    failure_context: &str,
+) -> Result<OpenAiGeneratedImages, AppError> {
+    let started_at_micros = current_utc_micros();
+    let request_payload = json!({
+        "model": model,
+        "size": size,
+        "candidateCount": candidate_count,
+        "promptChars": prompt.chars().count(),
+        "negativePromptChars": negative_prompt.map(str::chars).map(Iterator::count),
+        "referenceImageCount": reference_images.len(),
+    });
+    let result = create_vector_engine_image_generation_with_model(
+        http_client,
+        &settings.provider_settings(),
+        model,
+        prompt,
+        negative_prompt,
+        size,
+        candidate_count,
+        reference_images,
+        failure_context,
+    )
+    .await;
+    map_platform_image_result(
+        settings,
+        result,
+        "image_generation",
+        failure_context,
+        request_payload,
+        started_at_micros,
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn create_openai_nanobanana_generate_content(
+    http_client: &reqwest::Client,
+    settings: &OpenAiImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    aspect_ratio: &str,
+    image_size: &str,
+    reference_images: &[OpenAiReferenceImage],
+    failure_context: &str,
+) -> Result<OpenAiGeneratedImages, AppError> {
+    let started_at_micros = current_utc_micros();
+    let request_payload = json!({
+        "model": model,
+        "aspectRatio": aspect_ratio,
+        "imageSize": image_size,
+        "promptChars": prompt.chars().count(),
+        "negativePromptChars": negative_prompt.map(str::chars).map(Iterator::count),
+        "referenceImageCount": reference_images.len(),
+    });
+    let result = create_vector_engine_nanobanana_generate_content(
+        http_client,
+        &settings.provider_settings(),
+        model,
+        prompt,
+        negative_prompt,
+        aspect_ratio,
+        image_size,
+        reference_images,
+        failure_context,
+    )
+    .await;
+    map_platform_image_result(
+        settings,
+        result,
+        "nanobanana_generate_content",
+        failure_context,
+        request_payload,
+        started_at_micros,
+    )
+    .await
+}
+
 pub(crate) async fn create_openai_image_edit(
     http_client: &reqwest::Client,
     settings: &OpenAiImageSettings,
@@ -236,6 +326,49 @@ pub(crate) async fn create_openai_image_edit_with_references(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn create_openai_image_edit_with_references_and_model(
+    http_client: &reqwest::Client,
+    settings: &OpenAiImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    size: &str,
+    candidate_count: u32,
+    reference_images: &[OpenAiReferenceImage],
+    failure_context: &str,
+) -> Result<OpenAiGeneratedImages, AppError> {
+    let started_at_micros = current_utc_micros();
+    let request_payload = json!({
+        "model": model,
+        "size": size,
+        "promptChars": prompt.chars().count(),
+        "negativePromptChars": negative_prompt.map(str::chars).map(Iterator::count),
+        "referenceImageCount": reference_images.len(),
+    });
+    let result = create_vector_engine_image_edit_with_references_and_model(
+        http_client,
+        &settings.provider_settings(),
+        model,
+        prompt,
+        negative_prompt,
+        size,
+        candidate_count,
+        reference_images,
+        failure_context,
+    )
+    .await;
+    map_platform_image_result(
+        settings,
+        result,
+        "image_edit_with_references",
+        failure_context,
+        request_payload,
+        started_at_micros,
+    )
+    .await
+}
+
 #[cfg(test)]
 pub(crate) fn build_openai_image_request_body(
     prompt: &str,
@@ -445,7 +578,7 @@ mod tests {
         let body = build_openai_image_request_body(
             "雾海神殿",
             Some("文字，水印"),
-            "1280*720",
+            "16:9",
             2,
             &["data:image/png;base64,abcd".to_string()],
         );
diff --git a/server-rs/crates/api-server/src/prompt/big_fish.rs b/server-rs/crates/api-server/src/prompt/big_fish.rs
index 0cc0a3f74..ced20fa0d 100644
--- a/server-rs/crates/api-server/src/prompt/big_fish.rs
+++ b/server-rs/crates/api-server/src/prompt/big_fish.rs
@@ -116,7 +116,7 @@ pub(crate) fn build_big_fish_level_main_image_prompt(
         format!("形象描述：{}。", level.visual_description),
         format!("主图提示词：{}。", level.visual_prompt_seed),
         "等级对形象的影响规则：等级越高越霸气、有气场、看起来强大、画面细节丰富，等级级别越低越弱小、普通。最低等级为1级，最高等级可能是6-12级".to_string(),
-        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为纯绿色绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。".to_string(),
+        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。".to_string(),
         "背景要求：透明背景 PNG 风格，不出现任何场景、水草、气泡、阴影地面、UI、文字、logo、水印、对话框或边框；不要出现多只主体。".to_string(),
     ]
     .join("")
diff --git a/server-rs/crates/api-server/src/prompt/character_animation.rs b/server-rs/crates/api-server/src/prompt/character_animation.rs
index 7246e1411..492f72e16 100644
--- a/server-rs/crates/api-server/src/prompt/character_animation.rs
+++ b/server-rs/crates/api-server/src/prompt/character_animation.rs
@@ -53,7 +53,7 @@ fn build_image_sequence_prompt(
         "固定机位，单人，全身，侧身朝右，保持同一套服装、发型、武器和体型。".to_string(),
         "帧间动作连续，姿态逐步推进，不要换人，不要跳变，不要多余物体。".to_string(),
         if use_chroma_key {
-            "纯绿色背景，无地面装饰，方便后期抠像。".to_string()
+            "单一纯绿色 #00FF00 / RGB(0,255,0) 背景，无地面装饰，方便后期抠像。".to_string()
         } else {
             "背景尽量纯净，避免复杂场景。".to_string()
         },
@@ -94,7 +94,7 @@ fn build_npc_animation_prompt(
                 template.animation
             ),
             if use_chroma_key {
-                "背景为纯绿色绿幕，无其他人物和场景元素，方便后期抠像。".to_string()
+                "背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素，方便后期抠像。".to_string()
             } else {
                 "背景简洁纯净，无复杂场景。".to_string()
             },
@@ -123,7 +123,7 @@ fn build_npc_animation_prompt(
         "角色固定为同一人，侧身朝右，镜头稳定，轮廓清晰，武器不可丢失。".to_string(),
         "动作连贯，避免服装、发型、面部、武器随机漂移。".to_string(),
         if use_chroma_key {
-            "背景为纯绿色绿幕，无其他人物和场景元素，方便后期抠像。".to_string()
+            "背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素，方便后期抠像。".to_string()
         } else {
             "背景简洁纯净，无复杂场景。".to_string()
         },
@@ -200,10 +200,10 @@ fn build_video_action_prompt(
     [
         format!("生成有创意细节饱满的角色动作视频，动作英文名是 {}。", action_id),
         "角色固定为图1同一角色，保持右向斜侧身动作视角，镜头稳定，轮廓清晰，禁止退化成完全90度纯右视图。".to_string(),
-        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为纯绿色绿幕，只作为抠像底色，不出现建筑、室内布景、风景等场景内容。".to_string(),
+        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景等场景内容。".to_string(),
         format!("动作结构：{}。结尾要求：动作收束清楚，便于后续抽帧。", action_sequence),
         if use_chroma_key {
-            "背景为纯绿色绿幕，无其他人物和场景元素，方便后期抽帧与抠像。".to_string()
+            "背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素，方便后期抽帧与抠像。".to_string()
         } else {
             "背景简洁纯净，无其他人物和复杂场景元素，方便后期抽帧。".to_string()
         },
@@ -242,7 +242,7 @@ pub(crate) fn build_fallback_moderation_safe_animation_prompt(
             "非循环动作首尾回到角色标准站姿，中段完成动作变化。".to_string()
         },
         if use_chroma_key {
-            "背景为纯绿色绿幕，无其他人物和场景元素。".to_string()
+            "背景为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，无其他人物和场景元素。".to_string()
         } else {
             "背景简洁纯净。".to_string()
         },
diff --git a/server-rs/crates/api-server/src/prompt/character_visual.rs b/server-rs/crates/api-server/src/prompt/character_visual.rs
index b35b140c4..c2dfd4ccf 100644
--- a/server-rs/crates/api-server/src/prompt/character_visual.rs
+++ b/server-rs/crates/api-server/src/prompt/character_visual.rs
@@ -50,7 +50,7 @@ fn build_master_prompt(character_brief: &str) -> String {
         "单人，2D像素角色形象，头身比必须控制在1.5头身，主体完整可见，底部轮廓完整，身体比例稳定，轮廓清楚，适合后续制作 sprite sheet 动画。".to_string(),
         "视角要求：角色采用横版动作素材常用的右向斜侧身站姿，身体整体朝右，但保留少量正面信息，能读到面部轮廓与胸肩结构，不是完全 90 度纯右视图，也不是正面立绘。".to_string(),
         "主体要求：画面中只保留单个角色主体，不要额外人物、动物、召唤物、载具或陪体。".to_string(),
-        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为纯绿色绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。".to_string(),
+        "画面要求：1:1 正方形画布，画面中心构图，角色主体完整置于画面中央，不要裁切主体顶部和底部，不要镜头透视，不要特写。背景固定为单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，只作为抠像底色，不出现建筑、室内布景、风景、地面道具、漂浮物、烟雾叙事元素、文字或其他角色以外的场景内容。".to_string(),
         "风格要求：横版像素角色，细节精致，设计感足。使用深色清楚轮廓、稳定剪影、有限大色块和硬朗边缘，不要柔和厚涂插画感，发型、服装、配饰优先形成醒目可读的像素级识别点。".to_string(),
         "如果角色形象设定没有明确要求非人身体结构，默认优先使用人类或类人动作角色骨架。\
         默认将角色形象设定作用在角色自身的服装剪裁、材质、纹样、饰品、发光细节上。".to_string(),
diff --git a/server-rs/crates/api-server/src/puzzle.rs b/server-rs/crates/api-server/src/puzzle.rs
index e7f5ca4b1..13c042dde 100644
--- a/server-rs/crates/api-server/src/puzzle.rs
+++ b/server-rs/crates/api-server/src/puzzle.rs
@@ -336,7 +336,7 @@ pub(crate) fn build_puzzle_reference_image_too_large_message(actual_bytes: usize
 }
 
 const PUZZLE_LEVEL_SCENE_IMAGE_PROMPT: &str = "参考图作为拼图画面，生成对应的拼图游戏关卡画面，要求画面中所有元素精致且风格高度一致，画面中所有UI细节饱满精致、完成度高、顶级游戏品质\n\n画面元素：\n返回按钮位于顶部左上角，顶部中间显示关卡标题“第1关 影”和倒计时时间，右上角显示设置按钮\n画面中间是一个正方形的3*3拼图，拼图区域宽度与画面宽度同宽，紧贴画面横向边缘，拼图区域边界带有边框装饰\n拼图区域下方包含一个下一关按钮，仅在关卡完成时显示\n底部是三个贴合画面主题的道具按钮分别为“提示”、“原图”、“冻结”\n道具按钮上不要显示次数标注，返回按钮和设置按钮旁禁止标注文字";
-const PUZZLE_UI_SPRITESHEET_IMAGE_PROMPT: &str = "提取画面中的UI元素，将返回按钮、设置按钮、下一关按钮、提示按钮、原图按钮、冻结按钮整理成纯绿色绿幕背景的spritesheet。背景必须是统一纯绿色绿幕（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。按钮顺序必须按原图位置从左到右、从上到下排列：返回、设置、下一关、提示、原图、冻结。按钮素材内必须保留对应中文文字，每个按钮必须是独立完整图形，按钮之间保留足够纯绿色绿幕空白，不能相互接触、重叠或连成一片，方便运行态按自动边界检测识别矩形素材。返回按钮和设置按钮不要额外画白色外圈、白底圆环或浮雕外框，直接画扁平图标本体。按钮自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。禁止水印、数字、次数标注、透明背景、背景图、拼图块、棋盘、网格线、按钮外标签和额外按钮。";
+const PUZZLE_UI_SPRITESHEET_IMAGE_PROMPT: &str = "提取画面中的UI元素，将返回按钮、设置按钮、下一关按钮、提示按钮、原图按钮、冻结按钮整理成单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景的spritesheet。背景必须是统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕，背景平整无纹理、无渐变、无阴影、无场景内容，后端会在生图后将绿幕扣成透明并把透明背景 PNG 存到 OSS。按钮顺序必须按原图位置从左到右、从上到下排列：返回、设置、下一关、提示、原图、冻结。按钮素材内必须保留对应中文文字，每个按钮必须是独立完整图形，按钮之间保留足够单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕空白，不能相互接触、重叠或连成一片，方便运行态按自动边界检测识别矩形素材。返回按钮和设置按钮不要额外画白色外圈、白底圆环或浮雕外框，直接画扁平图标本体。按钮自身不得使用接近 #00FF00 的高饱和纯绿；绿色题材只能使用深绿、橄榄绿、金绿或蓝绿，并用清晰描边与绿幕区分。禁止水印、数字、次数标注、透明背景、背景图、拼图块、棋盘、网格线、按钮外标签和额外按钮。";
 const PUZZLE_LEVEL_BACKGROUND_IMAGE_PROMPT: &str = "移除参考图中所有UI元素、移除拼图画面，仅保留背景图，补全被覆盖的背景图内容。禁止在背景中出现人像或和拼图画面中主体一致的内容";
 mod handlers;
 pub(crate) use self::handlers::*;
diff --git a/server-rs/crates/api-server/src/puzzle/draft.rs b/server-rs/crates/api-server/src/puzzle/draft.rs
index 0f6e949e1..fe545dc56 100644
--- a/server-rs/crates/api-server/src/puzzle/draft.rs
+++ b/server-rs/crates/api-server/src/puzzle/draft.rs
@@ -2108,45 +2108,6 @@ pub(crate) fn apply_generated_puzzle_initial_metadata_to_session_snapshot(
     session
 }
 
-pub(crate) fn apply_generated_puzzle_metadata_to_session_snapshot(
-    mut session: PuzzleAgentSessionRecord,
-    target_level_id: &str,
-    metadata: &PuzzleLevelNaming,
-    previous_level_name: &str,
-    updated_at_micros: i64,
-) -> PuzzleAgentSessionRecord {
-    let Some(draft) = session.draft.as_mut() else {
-        return session;
-    };
-    let Some(target_index) = draft
-        .levels
-        .iter()
-        .position(|level| level.level_id == target_level_id)
-        .or_else(|| (!draft.levels.is_empty()).then_some(0))
-    else {
-        return session;
-    };
-
-    draft.levels[target_index].level_name = metadata.level_name.clone();
-    if metadata.ui_background_prompt.is_some() {
-        draft.levels[target_index].ui_background_prompt = metadata.ui_background_prompt.clone();
-    }
-
-    if target_index == 0 {
-        apply_generated_puzzle_initial_metadata_to_draft(
-            draft,
-            metadata,
-            previous_level_name,
-            updated_at_micros,
-        );
-    } else {
-        sync_puzzle_primary_draft_fields_from_level(draft);
-    }
-
-    session.updated_at = format_timestamp_micros(updated_at_micros);
-    session
-}
-
 pub(crate) fn apply_generated_puzzle_initial_metadata_to_draft(
     draft: &mut PuzzleResultDraftRecord,
     metadata: &PuzzleLevelNaming,
@@ -2196,45 +2157,3 @@ pub(crate) fn sync_puzzle_primary_draft_fields_from_level(draft: &mut PuzzleResu
         });
     }
 }
-
-pub(crate) fn replace_puzzle_session_draft_snapshot(
-    mut session: PuzzleAgentSessionRecord,
-    draft: PuzzleResultDraftRecord,
-    updated_at_micros: i64,
-) -> PuzzleAgentSessionRecord {
-    session.draft = Some(draft);
-    session.updated_at = format_timestamp_micros(updated_at_micros);
-    session
-}
-
-pub(crate) fn apply_generated_puzzle_ui_background_to_session_snapshot(
-    mut session: PuzzleAgentSessionRecord,
-    target_level_id: &str,
-    prompt: String,
-    image_src: String,
-    image_object_key: Option<String>,
-    updated_at_micros: i64,
-) -> PuzzleAgentSessionRecord {
-    let Some(draft) = session.draft.as_mut() else {
-        return session;
-    };
-    let Some(target_index) = draft
-        .levels
-        .iter()
-        .position(|level| level.level_id == target_level_id)
-        .or_else(|| (!draft.levels.is_empty()).then_some(0))
-    else {
-        return session;
-    };
-    let level = &mut draft.levels[target_index];
-    level.ui_background_prompt = Some(prompt);
-    level.ui_background_image_src = Some(image_src);
-    level.ui_background_image_object_key = image_object_key;
-    if target_index == 0 {
-        sync_puzzle_primary_draft_fields_from_level(draft);
-    }
-    session.progress_percent = session.progress_percent.max(96);
-    session.last_assistant_reply = Some("拼图 UI 背景图已生成。".to_string());
-    session.updated_at = format_timestamp_micros(updated_at_micros);
-    session
-}
diff --git a/server-rs/crates/api-server/src/puzzle/tests.rs b/server-rs/crates/api-server/src/puzzle/tests.rs
index dee3d4191..80f3f4152 100644
--- a/server-rs/crates/api-server/src/puzzle/tests.rs
+++ b/server-rs/crates/api-server/src/puzzle/tests.rs
@@ -109,7 +109,7 @@ fn puzzle_level_scene_spritesheet_and_background_requests_use_references() {
         spritesheet_body["prompt"]
             .as_str()
             .unwrap_or_default()
-            .contains("纯绿色绿幕背景")
+            .contains("单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景")
     );
     assert!(
         spritesheet_body["prompt"]
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation.rs
index 000f74984..ed9704ddf 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation.rs
@@ -11,6 +11,10 @@ mod tasks;
 mod tests;
 mod types;
 
+pub use generation::{generate_editor_background_music, generate_editor_sound_effect};
+pub(crate) use generation::{
+    generate_editor_background_music_for_owner, generate_editor_sound_effect_for_owner,
+};
 pub use handlers::{
     create_background_music_task, create_sound_effect_task,
     create_visual_novel_background_music_task, create_visual_novel_sound_effect_task,
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs
index 63fdd53e8..524a08608 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs
@@ -1,18 +1,298 @@
+use axum::Extension;
+use axum::http::StatusCode;
+use axum::{
+    Json,
+    extract::{State, rejection::JsonRejection},
+    response::Response,
+};
+use platform_oss::LegacyAssetPrefix;
+use serde_json::Value;
 use serde_json::json;
-use shared_contracts::creation_audio;
+use shared_contracts::{assets, creation_audio};
 
 use crate::{
-    http_error::AppError, state::AppState, tracking::record_external_generation_run_after_success,
+    api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
+    request_context::RequestContext, state::AppState,
+    tracking::record_external_generation_run_after_success,
 };
 
 use super::{
     clock::{current_utc_iso_text, current_utc_micros},
-    errors::{map_platform_audio_error, vector_engine_bad_gateway},
-    publish::wait_for_generated_audio_asset,
+    errors::{map_platform_audio_error, parse_json_payload, vector_engine_bad_gateway},
+    publish::{wait_for_generated_audio_asset, wait_for_generated_audio_asset_with_task_kind},
+    settings::require_vector_engine_audio_settings,
     tasks::create_sound_effect_task_response,
     types::{AudioAssetBindingTarget, AudioAssetSlot, GeneratedCreationAudioTarget},
 };
 
+const EDITOR_AUDIO_WIDTH: u32 = 420;
+const EDITOR_AUDIO_HEIGHT: u32 = 120;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct NormalizedEditorSoundEffectRequest {
+    pub(super) prompt: String,
+    pub(super) model: String,
+    pub(super) duration: u8,
+    pub(super) price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct NormalizedEditorBackgroundMusicRequest {
+    pub(super) gpt_description_prompt: String,
+    pub(super) make_instrumental: bool,
+    pub(super) price_mud_points: u32,
+}
+
+pub(super) fn normalize_editor_sound_effect_request(
+    payload: assets::EditorSoundEffectGenerateRequest,
+) -> Result<NormalizedEditorSoundEffectRequest, AppError> {
+    let model = normalize_editor_sound_model(payload.model.as_deref())?;
+    let expected_price_mud_points =
+        crate::editor_generation_config::editor_sound_effect_model_generation_mud_points(Some(
+            model.as_str(),
+        ));
+    if payload.price_mud_points != expected_price_mud_points {
+        return Err(editor_audio_bad_request(format!(
+            "音效生成泥点消耗不匹配，应为 {expected_price_mud_points}"
+        )));
+    }
+    Ok(NormalizedEditorSoundEffectRequest {
+        prompt: platform_audio::normalize_limited_text(
+            &payload.prompt,
+            "prompt",
+            platform_audio::VIDU_PROMPT_MAX_CHARS,
+        )
+        .map_err(map_platform_audio_error)?,
+        model,
+        duration: normalize_editor_sound_duration(payload.duration)?,
+        price_mud_points: expected_price_mud_points,
+    })
+}
+
+fn normalize_editor_sound_model(value: Option<&str>) -> Result<String, AppError> {
+    let model = platform_audio::normalize_optional_text(value)
+        .unwrap_or_else(|| platform_audio::VIDU_AUDIO_MODEL.to_string());
+    if model == platform_audio::VIDU_AUDIO_MODEL {
+        return Ok(model);
+    }
+    Err(editor_audio_bad_request(
+        "编辑器音效暂只支持 Vidu audio1.0 模型",
+    ))
+}
+
+fn normalize_editor_sound_duration(value: u8) -> Result<u8, AppError> {
+    if (2..=10).contains(&value) {
+        return Ok(value);
+    }
+    Err(editor_audio_bad_request("音效 duration 必须在 2-10 秒之间"))
+}
+
+pub(super) fn normalize_creation_sound_effect_duration(value: Option<u8>) -> Result<u8, AppError> {
+    let duration = value.unwrap_or(platform_audio::DEFAULT_SOUND_EFFECT_DURATION_SECONDS);
+    normalize_editor_sound_duration(duration)
+}
+
+pub(super) fn normalize_editor_background_music_request(
+    payload: assets::EditorBackgroundMusicGenerateRequest,
+) -> Result<NormalizedEditorBackgroundMusicRequest, AppError> {
+    let expected_price_mud_points =
+        crate::editor_generation_config::editor_background_music_model_generation_mud_points(Some(
+            platform_audio::SUNO_DEFAULT_MODEL,
+        ));
+    if payload.price_mud_points != expected_price_mud_points {
+        return Err(editor_audio_bad_request(format!(
+            "背景音乐生成泥点消耗不匹配，应为 {expected_price_mud_points}"
+        )));
+    }
+    Ok(NormalizedEditorBackgroundMusicRequest {
+        gpt_description_prompt: platform_audio::normalize_limited_text(
+            &payload.gpt_description_prompt,
+            "gpt_description_prompt",
+            platform_audio::SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS,
+        )
+        .map_err(map_platform_audio_error)?,
+        make_instrumental: true,
+        price_mud_points: expected_price_mud_points,
+    })
+}
+
+pub async fn generate_editor_sound_effect(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<assets::EditorSoundEffectGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    generate_editor_sound_effect_for_owner(
+        state,
+        request_context,
+        authenticated.claims().user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn generate_editor_sound_effect_for_owner(
+    state: AppState,
+    request_context: RequestContext,
+    owner_user_id: String,
+    payload: Result<Json<assets::EditorSoundEffectGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = parse_json_payload(&request_context, payload)?;
+    let normalized = normalize_editor_sound_effect_request(payload)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let settings = require_vector_engine_audio_settings(&state)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let http_client = platform_audio::build_vector_engine_audio_http_client(&settings)
+        .map_err(map_platform_audio_error)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let task = platform_audio::submit_editor_sound_effect_task(
+        &http_client,
+        &settings,
+        platform_audio::EditorSoundEffectTaskRequest {
+            prompt: normalized.prompt.clone(),
+            duration: normalized.duration,
+            seed: None,
+            model: Some(normalized.model.clone()),
+        },
+    )
+    .await
+    .map_err(map_platform_audio_error)
+    .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let generated = wait_for_generated_audio_asset_with_task_kind(
+        &state,
+        owner_user_id.as_str(),
+        task.task_id.clone(),
+        AudioAssetSlot::SoundEffect,
+        task.kind,
+        build_editor_audio_target(&task.task_id, "sound_effect", "editor_sound_effect"),
+    )
+    .await
+    .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let audio_src = generated
+        .audio_src
+        .ok_or_else(|| vector_engine_bad_gateway("音效生成完成但缺少播放地址"))
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        assets::EditorAudioGenerateResponse {
+            ok: true,
+            audio_src,
+            object_key: generated.object_key,
+            asset_object_id: generated.asset_object_id,
+            width: EDITOR_AUDIO_WIDTH,
+            height: EDITOR_AUDIO_HEIGHT,
+            source_type: "generated".to_string(),
+            prompt: normalized.prompt.clone(),
+            actual_prompt: Some(normalized.prompt),
+            model: normalized.model,
+            provider: generated.provider,
+            task_id: generated.task_id,
+            price_mud_points: normalized.price_mud_points,
+            audio_kind: "sound-effect".to_string(),
+        },
+    ))
+}
+
+pub async fn generate_editor_background_music(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<assets::EditorBackgroundMusicGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    generate_editor_background_music_for_owner(
+        state,
+        request_context,
+        authenticated.claims().user_id().to_string(),
+        payload,
+    )
+    .await
+}
+
+pub(crate) async fn generate_editor_background_music_for_owner(
+    state: AppState,
+    request_context: RequestContext,
+    owner_user_id: String,
+    payload: Result<Json<assets::EditorBackgroundMusicGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = parse_json_payload(&request_context, payload)?;
+    let normalized = normalize_editor_background_music_request(payload)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let settings = require_vector_engine_audio_settings(&state)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let http_client = platform_audio::build_vector_engine_audio_http_client(&settings)
+        .map_err(map_platform_audio_error)
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let task = platform_audio::submit_editor_background_music_task(
+        &http_client,
+        &settings,
+        platform_audio::EditorBackgroundMusicTaskRequest {
+            gpt_description_prompt: normalized.gpt_description_prompt.clone(),
+            make_instrumental: normalized.make_instrumental,
+            model: None,
+        },
+    )
+    .await
+    .map_err(map_platform_audio_error)
+    .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let generated = wait_for_generated_audio_asset(
+        &state,
+        owner_user_id.as_str(),
+        task.task_id.clone(),
+        AudioAssetSlot::BackgroundMusic,
+        build_editor_audio_target(&task.task_id, "background_music", "editor_background_music"),
+    )
+    .await
+    .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+    let audio_src = generated
+        .audio_src
+        .ok_or_else(|| vector_engine_bad_gateway("背景音乐生成完成但缺少播放地址"))
+        .map_err(|error| error.into_response_with_context(Some(&request_context)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        assets::EditorAudioGenerateResponse {
+            ok: true,
+            audio_src,
+            object_key: generated.object_key,
+            asset_object_id: generated.asset_object_id,
+            width: EDITOR_AUDIO_WIDTH,
+            height: EDITOR_AUDIO_HEIGHT,
+            source_type: "generated".to_string(),
+            prompt: normalized.gpt_description_prompt.clone(),
+            actual_prompt: Some(normalized.gpt_description_prompt),
+            model: platform_audio::SUNO_DEFAULT_MODEL.to_string(),
+            provider: generated.provider,
+            task_id: generated.task_id,
+            price_mud_points: normalized.price_mud_points,
+            audio_kind: "background-music".to_string(),
+        },
+    ))
+}
+
+fn build_editor_audio_target(
+    task_id: &str,
+    slot: &'static str,
+    asset_kind: &'static str,
+) -> AudioAssetBindingTarget {
+    AudioAssetBindingTarget {
+        entity_kind: "editor_audio".to_string(),
+        entity_id: task_id.to_string(),
+        slot: slot.to_string(),
+        asset_kind: asset_kind.to_string(),
+        profile_id: None,
+        storage_prefix: LegacyAssetPrefix::CharacterDrafts,
+        storage_scope: "editor_audio".to_string(),
+    }
+}
+
+fn editor_audio_bad_request(message: impl Into<String>) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": platform_audio::VECTOR_ENGINE_PROVIDER,
+        "message": message.into(),
+    }))
+}
+
 pub(crate) async fn generate_sound_effect_asset_for_creation(
     state: &AppState,
     owner_user_id: &str,
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs
index 8fd56e60d..5d3ee628b 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs
@@ -14,6 +14,7 @@ use crate::{
 
 use super::{
     errors::{map_platform_audio_error, parse_json_payload},
+    generation::normalize_creation_sound_effect_duration,
     publish::publish_generated_audio_asset,
     settings::require_vector_engine_audio_settings,
     targets::{
@@ -82,10 +83,8 @@ pub async fn create_visual_novel_sound_effect_task(
         &settings,
         SoundEffectTaskRequest {
             prompt: payload.prompt,
-            duration: payload
-                .duration
-                .unwrap_or(platform_audio::DEFAULT_SOUND_EFFECT_DURATION_SECONDS)
-                .clamp(2, 10),
+            duration: normalize_creation_sound_effect_duration(payload.duration)
+                .map_err(|error| error.into_response_with_context(Some(&request_context)))?,
             seed: payload.seed,
         },
     )
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/persist.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/persist.rs
index 0802b8527..5900466fb 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/persist.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/persist.rs
@@ -17,6 +17,7 @@ use super::{
 #[derive(Clone, Debug)]
 pub(super) struct PersistedAudioAsset {
     pub(super) asset_object_id: String,
+    pub(super) object_key: String,
     pub(super) audio_src: String,
 }
 
@@ -25,7 +26,8 @@ pub(super) async fn persist_generated_audio_asset(
     http_client: &reqwest::Client,
     owner_user_id: &str,
     task_id: &str,
-    slot: AudioAssetSlot,
+    _slot: AudioAssetSlot,
+    task_kind: platform_audio::AudioTaskKind,
     target: AudioAssetBindingTarget,
     audio: DownloadedAudio,
 ) -> Result<PersistedAudioAsset, AppError> {
@@ -41,7 +43,7 @@ pub(super) async fn persist_generated_audio_asset(
         platform_audio::prepare_generated_audio_put_request(GeneratedAudioPersistInput {
             owner_user_id: owner_user_id.to_string(),
             task_id: task_id.to_string(),
-            task_kind: slot.task_kind(),
+            task_kind,
             target: GeneratedAudioPersistTarget {
                 entity_kind: target.entity_kind.clone(),
                 entity_id: target.entity_id.clone(),
@@ -110,6 +112,7 @@ pub(super) async fn persist_generated_audio_asset(
 
     Ok(PersistedAudioAsset {
         asset_object_id: asset_object.asset_object_id,
+        object_key: put_result.object_key,
         audio_src: put_result.legacy_public_path,
     })
 }
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs
index 68795fea4..c64ec2539 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs
@@ -23,6 +23,25 @@ pub(super) async fn publish_generated_audio_asset(
     task_id: String,
     slot: AudioAssetSlot,
     target: AudioAssetBindingTarget,
+) -> Result<creation_audio::GeneratedAudioAssetResponse, AppError> {
+    publish_generated_audio_asset_with_task_kind(
+        state,
+        owner_user_id,
+        task_id,
+        slot,
+        slot.task_kind(),
+        target,
+    )
+    .await
+}
+
+pub(super) async fn publish_generated_audio_asset_with_task_kind(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: String,
+    slot: AudioAssetSlot,
+    task_kind: platform_audio::AudioTaskKind,
+    target: AudioAssetBindingTarget,
 ) -> Result<creation_audio::GeneratedAudioAssetResponse, AppError> {
     let task_id = platform_audio::normalize_limited_text(&task_id, "taskId", 160)
         .map_err(map_platform_audio_error)?;
@@ -33,7 +52,7 @@ pub(super) async fn publish_generated_audio_asset(
         platform_audio::resolve_audio_task_download_urls(
             &http_client,
             &settings,
-            slot.task_kind(),
+            task_kind,
             &task_id,
         )
         .await
@@ -43,9 +62,10 @@ pub(super) async fn publish_generated_audio_asset(
         return Ok(creation_audio::GeneratedAudioAssetResponse {
             kind: slot.creation_contract_kind(),
             task_id,
-            provider: slot.provider().to_string(),
+            provider: task_kind.provider().to_string(),
             status: status.clone(),
             asset_object_id: None,
+            object_key: None,
             asset_kind: None,
             audio_src: None,
         });
@@ -71,16 +91,20 @@ pub(super) async fn publish_generated_audio_asset(
         billing_asset_id.as_str(),
         points_cost,
         async {
-            let audio =
-                platform_audio::download_generated_audio(&http_client, &audio_url, slot.provider())
-                    .await
-                    .map_err(map_platform_audio_error)?;
+            let audio = platform_audio::download_generated_audio(
+                &http_client,
+                &audio_url,
+                task_kind.provider(),
+            )
+            .await
+            .map_err(map_platform_audio_error)?;
             persist_generated_audio_asset(
                 state,
                 &http_client,
                 owner_user_id,
                 &task_id,
                 slot,
+                task_kind,
                 target.clone(),
                 audio,
             )
@@ -92,9 +116,10 @@ pub(super) async fn publish_generated_audio_asset(
     Ok(creation_audio::GeneratedAudioAssetResponse {
         kind: slot.creation_contract_kind(),
         task_id,
-        provider: slot.provider().to_string(),
+        provider: task_kind.provider().to_string(),
         status: "completed".to_string(),
         asset_object_id: Some(persisted.asset_object_id),
+        object_key: Some(persisted.object_key),
         asset_kind: Some(target.asset_kind),
         audio_src: Some(persisted.audio_src),
     })
@@ -106,14 +131,34 @@ pub(super) async fn wait_for_generated_audio_asset(
     task_id: String,
     slot: AudioAssetSlot,
     target: AudioAssetBindingTarget,
+) -> Result<creation_audio::GeneratedAudioAssetResponse, AppError> {
+    wait_for_generated_audio_asset_with_task_kind(
+        state,
+        owner_user_id,
+        task_id,
+        slot,
+        slot.task_kind(),
+        target,
+    )
+    .await
+}
+
+pub(super) async fn wait_for_generated_audio_asset_with_task_kind(
+    state: &AppState,
+    owner_user_id: &str,
+    task_id: String,
+    slot: AudioAssetSlot,
+    task_kind: platform_audio::AudioTaskKind,
+    target: AudioAssetBindingTarget,
 ) -> Result<creation_audio::GeneratedAudioAssetResponse, AppError> {
     let mut latest_status = String::new();
     for _ in 0..40 {
-        let response = publish_generated_audio_asset(
+        let response = publish_generated_audio_asset_with_task_kind(
             state,
             owner_user_id,
             task_id.clone(),
             slot,
+            task_kind,
             target.clone(),
         )
         .await?;
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs
index fec797c0c..8a17b5466 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs
@@ -3,7 +3,10 @@ use shared_contracts::creation_audio;
 
 use crate::{http_error::AppError, state::AppState};
 
-use super::{errors::map_platform_audio_error, settings::require_vector_engine_audio_settings};
+use super::{
+    errors::map_platform_audio_error, generation::normalize_creation_sound_effect_duration,
+    settings::require_vector_engine_audio_settings,
+};
 
 pub(super) async fn create_sound_effect_task_response(
     state: &AppState,
@@ -19,9 +22,7 @@ pub(super) async fn create_sound_effect_task_response(
         &settings,
         SoundEffectTaskRequest {
             prompt,
-            duration: duration
-                .unwrap_or(platform_audio::DEFAULT_SOUND_EFFECT_DURATION_SECONDS)
-                .clamp(2, 10),
+            duration: normalize_creation_sound_effect_duration(duration)?,
             seed,
         },
     )
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs
index 566a5bd97..d27925d14 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs
@@ -1,8 +1,12 @@
 use axum::http::StatusCode;
 use platform_oss::LegacyAssetPrefix;
-use shared_contracts::creation_audio;
+use shared_contracts::{assets, creation_audio};
 
 use super::{
+    generation::{
+        normalize_creation_sound_effect_duration, normalize_editor_background_music_request,
+        normalize_editor_sound_effect_request,
+    },
     publish::resolve_creation_audio_points_cost,
     targets::{build_creation_audio_target, creation_audio_generation_disabled_error_for_target},
     types::{AudioAssetBindingTarget, AudioAssetSlot},
@@ -77,3 +81,123 @@ fn disabled_creation_audio_targets_return_gone_including_wooden_fish_sound_effec
         .expect_err("wooden fish hit sound target should be disabled");
     assert_eq!(error.status_code(), StatusCode::GONE);
 }
+
+#[test]
+fn editor_sound_effect_request_normalizes_prompt_duration_and_price() {
+    let normalized =
+        normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest {
+            prompt: "  金币掉落叮当声  ".to_string(),
+            model: None,
+            duration: 7,
+            price_mud_points: 10,
+        })
+        .expect("editor sound effect request should normalize");
+
+    assert_eq!(normalized.prompt, "金币掉落叮当声");
+    assert_eq!(normalized.model, platform_audio::VIDU_AUDIO_MODEL);
+    assert_eq!(normalized.duration, 7);
+    assert_eq!(normalized.price_mud_points, 10);
+}
+
+#[test]
+fn editor_sound_effect_request_accepts_only_vidu_audio_model() {
+    let normalized =
+        normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest {
+            prompt: "金币掉落叮当声".to_string(),
+            model: Some(" audio1.0 ".to_string()),
+            duration: 5,
+            price_mud_points: 10,
+        })
+        .expect("Vidu audio model should be accepted");
+
+    assert_eq!(normalized.model, platform_audio::VIDU_AUDIO_MODEL);
+
+    let error = normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest {
+        prompt: "金币掉落叮当声".to_string(),
+        model: Some(platform_audio::SUNO_DEFAULT_MODEL.to_string()),
+        duration: 5,
+        price_mud_points: 10,
+    })
+    .expect_err("Suno text-to-sound should be disabled for editor sound effects");
+
+    assert!(error.to_string().contains("Vidu"));
+}
+
+#[test]
+fn editor_sound_effect_request_rejects_duration_outside_vidu_range() {
+    for duration in [1, 11] {
+        let error =
+            normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest {
+                prompt: "按钮点击".to_string(),
+                model: None,
+                duration,
+                price_mud_points: 10,
+            })
+            .expect_err("duration outside 2-10 seconds should fail");
+
+        assert!(error.to_string().contains("2-10"));
+    }
+}
+
+#[test]
+fn creation_sound_effect_duration_rejects_outside_vidu_range() {
+    assert_eq!(
+        normalize_creation_sound_effect_duration(None).expect("default duration should pass"),
+        platform_audio::DEFAULT_SOUND_EFFECT_DURATION_SECONDS
+    );
+    assert_eq!(
+        normalize_creation_sound_effect_duration(Some(2)).expect("2 seconds should pass"),
+        2
+    );
+    assert_eq!(
+        normalize_creation_sound_effect_duration(Some(10)).expect("10 seconds should pass"),
+        10
+    );
+
+    for duration in [Some(1), Some(11)] {
+        let error = normalize_creation_sound_effect_duration(duration)
+            .expect_err("duration outside Vidu 2-10 seconds should fail");
+        assert!(error.to_string().contains("2-10"));
+    }
+}
+
+#[test]
+fn editor_background_music_request_forces_instrumental_and_price() {
+    let normalized =
+        normalize_editor_background_music_request(assets::EditorBackgroundMusicGenerateRequest {
+            gpt_description_prompt: "  森林冒险背景音乐  ".to_string(),
+            make_instrumental: false,
+            price_mud_points: 5,
+        })
+        .expect("editor background music request should normalize");
+
+    assert_eq!(normalized.gpt_description_prompt, "森林冒险背景音乐");
+    assert!(normalized.make_instrumental);
+    assert_eq!(normalized.price_mud_points, 5);
+}
+
+#[test]
+fn editor_background_music_request_rejects_prompt_over_documented_limit() {
+    let error =
+        normalize_editor_background_music_request(assets::EditorBackgroundMusicGenerateRequest {
+            gpt_description_prompt: "乐".repeat(201),
+            make_instrumental: true,
+            price_mud_points: 5,
+        })
+        .expect_err("Suno gpt_description_prompt should follow Apifox 200 char limit");
+
+    assert!(error.to_string().contains("gpt_description_prompt"));
+}
+
+#[test]
+fn editor_audio_rejects_price_mismatch() {
+    let error = normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest {
+        prompt: "点击按钮".to_string(),
+        model: None,
+        duration: 5,
+        price_mud_points: 5,
+    })
+    .expect_err("wrong sound effect price should fail");
+
+    assert!(error.to_string().contains("泥点"));
+}
diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs
index a424f46eb..8a141b54b 100644
--- a/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs
+++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs
@@ -46,10 +46,6 @@ impl AudioAssetSlot {
         }
     }
 
-    pub(super) fn provider(self) -> &'static str {
-        self.task_kind().provider()
-    }
-
     pub(super) fn asset_kind(self) -> &'static str {
         match self {
             Self::BackgroundMusic => MUSIC_ASSET_KIND,
diff --git a/server-rs/crates/api-server/src/wooden_fish.rs b/server-rs/crates/api-server/src/wooden_fish.rs
index 9f583dd66..fc2d22684 100644
--- a/server-rs/crates/api-server/src/wooden_fish.rs
+++ b/server-rs/crates/api-server/src/wooden_fish.rs
@@ -1131,7 +1131,7 @@ async fn generate_wooden_fish_image_assets(
 
 fn build_wooden_fish_hit_object_prompt(prompt: &str) -> String {
     format!(
-        "生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。\n新主题为：{}",
+        "生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。尺寸1:1，先输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，背景必须严格使用 #00FF00 / RGB(0,255,0) 且平整无纹理、无渐变、无阴影、无道具，主体完整居中，主体边缘必须干净，不要直接输出透明底。随后由服务端对绿色背景主体图做抠图去除绿色背景。最终结果只保留单个敲击物图案，禁止黑底、白底、棋盘格、纸板底或任何实底背景；主体本身不要使用与绿幕接近的纯绿色，若新主题天然包含绿色，请改用偏深、偏黄或偏蓝的绿色并与绿幕清晰区分。\n新主题为：{}",
         clean_string(prompt, DEFAULT_HIT_OBJECT_PROMPT)
     )
 }
@@ -1145,7 +1145,7 @@ fn build_wooden_fish_background_prompt(prompt: &str) -> String {
 
 fn build_wooden_fish_back_button_prompt(prompt: &str) -> String {
     format!(
-        "生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，按钮主体在画布中的视觉尺寸比当前模板再放大约 50%，圆心居中，圆形外沿加一圈和主题色搭配的干净外描边，让它更像一个按钮，但仍然只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 UI 面板、木槌或敲击道具。尺寸1:1，输出绿色背景主体图（纯绿色绿幕），背景必须是单一纯绿色 #00FF00 且平整无纹理、无渐变、无阴影。按钮主体边缘干净，后续由服务端扣除绿色背景；按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请仅在圆形底色上使用偏深、偏黄或偏蓝的主题绿色，并用更高对比的箭头颜色区分。\n主题为：{}",
+        "生成敲木鱼左上角返回按钮图。要求以参考图-去除绿色背景后的敲击物主体和背景环境图为主题、画风、材质和配色参考，但参考图只用来约束圆形底色和中央左箭头的颜色搭配，不要继承复杂造型、花纹、浮雕边、异形外框或装饰图案。按钮必须始终是标准圆形，整体像单个圆形图标，按钮主体在画布中的视觉尺寸比当前模板再放大约 50%，圆心居中，圆形外沿加一圈和主题色搭配的干净外描边，让它更像一个按钮，但仍然只保留一个清晰、简洁、居中的向左返回箭头，不要出现文字、数字、水印、按钮外标签、额外 UI 面板、木槌或敲击道具。尺寸1:1，输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图，背景必须严格使用 #00FF00 / RGB(0,255,0) 且平整无纹理、无渐变、无阴影。按钮主体边缘干净，后续由服务端扣除绿色背景；按钮底色不要使用与绿幕接近的纯绿色，若主题天然包含绿色，请仅在圆形底色上使用偏深、偏黄或偏蓝的主题绿色，并用更高对比的箭头颜色区分。\n主题为：{}",
         clean_string(prompt, DEFAULT_HIT_OBJECT_PROMPT)
     )
 }
@@ -1597,8 +1597,7 @@ mod tests {
             "生成敲木鱼新样式，要求结构，画风与参考图保持高度一致，新样式颜色搭配使用新主题对应的颜色。"
         ));
         assert!(prompt.contains("尺寸1:1"));
-        assert!(prompt.contains("绿色背景主体图"));
-        assert!(prompt.contains("纯绿色绿幕"));
+        assert!(prompt.contains("先输出单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景主体图"));
         assert!(prompt.contains("#00FF00"));
         assert!(prompt.contains("不要直接输出透明底"));
         assert!(prompt.contains("主体本身不要使用与绿幕接近的纯绿色"));
diff --git a/server-rs/crates/platform-audio/src/client.rs b/server-rs/crates/platform-audio/src/client.rs
index b1233e057..d993d1005 100644
--- a/server-rs/crates/platform-audio/src/client.rs
+++ b/server-rs/crates/platform-audio/src/client.rs
@@ -4,11 +4,14 @@ use reqwest::header;
 use serde_json::Value;
 
 use crate::response::{
-    extract_audio_urls, extract_string_by_path, find_first_string_by_key, normalize_task_status,
+    extract_audio_urls, extract_string_by_path, extract_suno_clip_ids, find_first_string_by_key,
+    is_failed_task_status, normalize_task_status,
 };
 use crate::{
     AudioError, AudioTaskKind, AudioTaskResponse, BackgroundMusicTaskRequest,
-    SoundEffectTaskRequest, VectorEngineAudioSettings, build_background_music_task_body,
+    EditorBackgroundMusicTaskRequest, EditorSoundEffectTaskRequest, SoundEffectTaskRequest,
+    VectorEngineAudioSettings, build_background_music_task_body,
+    build_editor_background_music_task_body, build_editor_sound_effect_task_body,
     build_sound_effect_task_body,
 };
 
@@ -41,12 +44,9 @@ pub async fn submit_background_music_task(
         "提交 Suno 背景音乐任务失败",
     )
     .await?;
-    let task_id = extract_string_by_path(&response, &["data"])
-        .or_else(|| find_first_string_by_key(&response, "task_id"))
-        .or_else(|| find_first_string_by_key(&response, "taskId"))
-        .ok_or_else(|| {
-            AudioError::missing_audio("提交 Suno 背景音乐任务失败：上游未返回任务 ID")
-        })?;
+    let task_id = extract_submit_task_id(&response).ok_or_else(|| {
+        AudioError::missing_audio("提交 Suno 背景音乐任务失败：上游未返回任务 ID")
+    })?;
 
     Ok(AudioTaskResponse {
         kind: AudioTaskKind::BackgroundMusic,
@@ -70,8 +70,7 @@ pub async fn submit_sound_effect_task(
         "提交 Vidu 音效任务失败",
     )
     .await?;
-    let task_id = find_first_string_by_key(&response, "task_id")
-        .or_else(|| find_first_string_by_key(&response, "taskId"))
+    let task_id = extract_submit_task_id(&response)
         .ok_or_else(|| AudioError::missing_audio("提交 Vidu 音效任务失败：上游未返回任务 ID"))?;
     let status = find_first_string_by_key(&response, "state").unwrap_or_else(|| "created".into());
 
@@ -83,6 +82,58 @@ pub async fn submit_sound_effect_task(
     })
 }
 
+pub async fn submit_editor_background_music_task(
+    http_client: &reqwest::Client,
+    settings: &VectorEngineAudioSettings,
+    request: EditorBackgroundMusicTaskRequest,
+) -> Result<AudioTaskResponse, AudioError> {
+    let body = build_editor_background_music_task_body(request)?;
+    let response = post_vector_engine_json(
+        http_client,
+        settings,
+        AudioTaskKind::BackgroundMusic.submit_path(),
+        body,
+        "提交编辑器背景音乐任务失败",
+    )
+    .await?;
+    let task_id = extract_submit_task_id(&response).ok_or_else(|| {
+        AudioError::missing_audio("提交编辑器背景音乐任务失败：上游未返回任务 ID")
+    })?;
+
+    Ok(AudioTaskResponse {
+        kind: AudioTaskKind::BackgroundMusic,
+        task_id,
+        provider: AudioTaskKind::BackgroundMusic.provider().to_string(),
+        status: "submitted".to_string(),
+    })
+}
+
+pub async fn submit_editor_sound_effect_task(
+    http_client: &reqwest::Client,
+    settings: &VectorEngineAudioSettings,
+    request: EditorSoundEffectTaskRequest,
+) -> Result<AudioTaskResponse, AudioError> {
+    let body = build_editor_sound_effect_task_body(request)?;
+    let response = post_vector_engine_json(
+        http_client,
+        settings,
+        AudioTaskKind::SoundEffect.submit_path(),
+        body,
+        "提交编辑器音效任务失败",
+    )
+    .await?;
+    let task_id = extract_submit_task_id(&response)
+        .ok_or_else(|| AudioError::missing_audio("提交编辑器音效任务失败：上游未返回任务 ID"))?;
+    let status = find_first_string_by_key(&response, "state").unwrap_or_else(|| "created".into());
+
+    Ok(AudioTaskResponse {
+        kind: AudioTaskKind::SoundEffect,
+        task_id,
+        provider: AudioTaskKind::SoundEffect.provider().to_string(),
+        status,
+    })
+}
+
 async fn fetch_audio_task_payload(
     http_client: &reqwest::Client,
     settings: &VectorEngineAudioSettings,
@@ -96,6 +147,7 @@ async fn fetch_audio_task_payload(
         match kind {
             AudioTaskKind::BackgroundMusic => "查询 Suno 背景音乐任务失败",
             AudioTaskKind::SoundEffect => "查询 Vidu 音效任务失败",
+            AudioTaskKind::SunoSoundEffect => "查询 Suno 音效任务失败",
         },
     )
     .await
@@ -116,39 +168,80 @@ pub async fn resolve_audio_task_download_urls(
             .unwrap_or(""),
     );
     let mut audio_urls = extract_audio_urls(&task_payload);
-    if kind == AudioTaskKind::BackgroundMusic && audio_urls.is_empty() {
-        if let Some(clip_id) = extract_string_by_path(&task_payload, &["data"]).and_then(|value| {
-            if value.trim().is_empty() {
-                None
-            } else {
-                Some(value)
-            }
-        }) {
-            let wav_payload = get_vector_engine_json(
+    if matches!(
+        kind,
+        AudioTaskKind::BackgroundMusic | AudioTaskKind::SunoSoundEffect
+    ) && audio_urls.is_empty()
+    {
+        let clip_ids = extract_suno_clip_ids(&task_payload);
+        let has_clip_ids = !clip_ids.is_empty();
+        let mut latest_wav_error = None;
+        for clip_id in clip_ids {
+            let wav_payload = match get_vector_engine_json(
                 http_client,
                 settings,
                 &format!("/suno/act/wav/{}", urlencoding::encode(clip_id.as_str())),
-                "获取 Suno wav 音频失败",
+                match kind {
+                    AudioTaskKind::SunoSoundEffect => "获取 Suno 音效 wav 失败",
+                    _ => "获取 Suno wav 音频失败",
+                },
             )
-            .await?;
+            .await
+            {
+                Ok(payload) => {
+                    latest_wav_error = None;
+                    payload
+                }
+                Err(error) => {
+                    latest_wav_error = Some(error);
+                    continue;
+                }
+            };
             audio_urls = extract_audio_urls(&wav_payload);
+            if !audio_urls.is_empty() {
+                break;
+            }
+        }
+        // 中文注释：Suno 任务完成后可能先返回 clip id，/suno/act/wav/{clip_id}
+        // 可能返回 404/业务错误或 wav_file_url 仍为 null。此时不能把任务判成失败，
+        // 让上层轮询继续等待；真正失败仍交给 fetch 任务状态判断。
+        if let Some(status) = resolve_suno_status_after_wav_probe(
+            &status,
+            has_clip_ids,
+            &audio_urls,
+            latest_wav_error,
+        ) {
+            return Ok((status, audio_urls));
         }
     }
     Ok((status, audio_urls))
 }
 
+fn should_wait_for_suno_wav_audio(status: &str, has_clip_ids: bool, audio_urls: &[String]) -> bool {
+    audio_urls.is_empty() && has_clip_ids && !is_failed_task_status(status)
+}
+
+fn resolve_suno_status_after_wav_probe(
+    status: &str,
+    has_clip_ids: bool,
+    audio_urls: &[String],
+    _latest_wav_error: Option<AudioError>,
+) -> Option<String> {
+    if should_wait_for_suno_wav_audio(status, has_clip_ids, audio_urls) {
+        return Some("processing".to_string());
+    }
+    None
+}
+
 async fn get_vector_engine_json(
     http_client: &reqwest::Client,
     settings: &VectorEngineAudioSettings,
     path: &str,
     failure_context: &str,
 ) -> Result<Value, AudioError> {
+    let endpoint = vector_engine_audio_endpoint_url(settings, path);
     let response = http_client
-        .get(format!(
-            "{}{}",
-            settings.base_url.trim_end_matches('/'),
-            path
-        ))
+        .get(endpoint.as_str())
         .header(
             header::AUTHORIZATION,
             format!("Bearer {}", settings.api_key),
@@ -156,7 +249,7 @@ async fn get_vector_engine_json(
         .header(header::ACCEPT, "application/json")
         .send()
         .await
-        .map_err(|error| map_reqwest_error(failure_context, path, error))?;
+        .map_err(|error| map_reqwest_error(failure_context, endpoint.as_str(), error))?;
     parse_vector_engine_response(response, failure_context).await
 }
 
@@ -167,12 +260,9 @@ async fn post_vector_engine_json(
     body: Value,
     failure_context: &str,
 ) -> Result<Value, AudioError> {
+    let endpoint = vector_engine_audio_endpoint_url(settings, path);
     let response = http_client
-        .post(format!(
-            "{}{}",
-            settings.base_url.trim_end_matches('/'),
-            path
-        ))
+        .post(endpoint.as_str())
         .header(
             header::AUTHORIZATION,
             format!("Bearer {}", settings.api_key),
@@ -182,10 +272,33 @@ async fn post_vector_engine_json(
         .json(&body)
         .send()
         .await
-        .map_err(|error| map_reqwest_error(failure_context, path, error))?;
+        .map_err(|error| map_reqwest_error(failure_context, endpoint.as_str(), error))?;
     parse_vector_engine_response(response, failure_context).await
 }
 
+pub(crate) fn vector_engine_audio_endpoint_url(
+    settings: &VectorEngineAudioSettings,
+    path: &str,
+) -> String {
+    let base_url = normalize_vector_engine_audio_base_url(settings.base_url.as_str());
+    let path = path.trim();
+    if path.starts_with('/') {
+        format!("{base_url}{path}")
+    } else {
+        format!("{base_url}/{path}")
+    }
+}
+
+fn normalize_vector_engine_audio_base_url(base_url: &str) -> String {
+    let normalized = base_url.trim().trim_end_matches('/');
+    // 中文注释：Suno / Vidu 音频接口在 VectorEngine 根路径下，不能拼成 /v1/suno/*。
+    normalized
+        .strip_suffix("/v1")
+        .unwrap_or(normalized)
+        .trim_end_matches('/')
+        .to_string()
+}
+
 async fn parse_vector_engine_response(
     response: reqwest::Response,
     failure_context: &str,
@@ -205,7 +318,7 @@ async fn parse_vector_engine_response(
     })?;
     if !status.is_success() {
         return Err(AudioError::upstream(
-            failure_context.to_string(),
+            build_upstream_error_message(failure_context, status.as_u16(), raw_text.as_str()),
             status.as_u16(),
             truncate_raw(raw_text.as_str()),
         ));
@@ -217,18 +330,12 @@ async fn parse_vector_engine_response(
             truncate_raw(raw_text.as_str()),
         )
     })?;
-    if let Some(code) = payload.get("code").and_then(Value::as_str)
-        && !matches!(
-            code.trim().to_ascii_lowercase().as_str(),
-            "success" | "succeeded" | "ok"
-        )
+    if let Some(code) = payload.get("code")
+        && !is_success_response_code(code)
     {
         return Err(AudioError::upstream(
-            payload
-                .get("message")
-                .and_then(Value::as_str)
-                .unwrap_or(failure_context)
-                .to_string(),
+            extract_upstream_payload_message(&payload)
+                .unwrap_or_else(|| failure_context.to_string()),
             status.as_u16(),
             truncate_raw(raw_text.as_str()),
         ));
@@ -253,3 +360,171 @@ fn map_reqwest_error(failure_context: &str, endpoint: &str, error: reqwest::Erro
 fn truncate_raw(raw_text: &str) -> String {
     raw_text.chars().take(800).collect()
 }
+
+fn extract_submit_task_id(response: &Value) -> Option<String> {
+    // 中文注释：Suno 音频提交接口文档未声明响应结构，实际可能直接把任务 ID 放在 data 字符串或 data 对象中。
+    extract_string_by_path(response, &["data"])
+        .or_else(|| extract_string_by_path(response, &["data", "task_id"]))
+        .or_else(|| extract_string_by_path(response, &["data", "taskId"]))
+        .or_else(|| extract_string_by_path(response, &["data", "id"]))
+        .or_else(|| find_first_string_by_key(response, "task_id"))
+        .or_else(|| find_first_string_by_key(response, "taskId"))
+        .or_else(|| find_first_string_by_key(response, "id"))
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn build_upstream_error_message(failure_context: &str, status: u16, raw_text: &str) -> String {
+    let excerpt = truncate_raw(raw_text);
+    if excerpt.trim().is_empty() {
+        return format!("{failure_context}：上游 HTTP {status}");
+    }
+    format!("{failure_context}：上游 HTTP {status}：{excerpt}")
+}
+
+fn is_success_response_code(code: &Value) -> bool {
+    match code {
+        Value::String(code) => matches!(
+            code.trim().to_ascii_lowercase().as_str(),
+            "success" | "succeeded" | "ok" | "0" | "200"
+        ),
+        Value::Number(code) => code.as_i64().is_some_and(|code| code == 0 || code == 200),
+        _ => false,
+    }
+}
+
+fn extract_upstream_payload_message(payload: &Value) -> Option<String> {
+    payload
+        .get("message")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|message| !message.is_empty())
+        .map(ToOwned::to_owned)
+        .or_else(|| {
+            payload
+                .get("error")
+                .and_then(|value| match value {
+                    Value::String(message) => Some(message.as_str()),
+                    Value::Object(object) => object
+                        .get("message")
+                        .and_then(Value::as_str)
+                        .or_else(|| object.get("detail").and_then(Value::as_str)),
+                    _ => None,
+                })
+                .map(str::trim)
+                .filter(|message| !message.is_empty())
+                .map(ToOwned::to_owned)
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn settings(base_url: &str) -> VectorEngineAudioSettings {
+        VectorEngineAudioSettings {
+            base_url: base_url.to_string(),
+            api_key: "test-key".to_string(),
+            request_timeout_ms: 1_000,
+        }
+    }
+
+    #[test]
+    fn audio_endpoint_urls_strip_v1_for_root_level_suno_paths() {
+        assert_eq!(
+            vector_engine_audio_endpoint_url(
+                &settings("https://api.vectorengine.cn"),
+                "/suno/submit/music"
+            ),
+            "https://api.vectorengine.cn/suno/submit/music"
+        );
+        assert_eq!(
+            vector_engine_audio_endpoint_url(
+                &settings("https://api.vectorengine.cn/v1"),
+                "/suno/submit/music"
+            ),
+            "https://api.vectorengine.cn/suno/submit/music"
+        );
+        assert_eq!(
+            vector_engine_audio_endpoint_url(
+                &settings(" https://api.vectorengine.cn/v1/ "),
+                "suno/submit/music"
+            ),
+            "https://api.vectorengine.cn/suno/submit/music"
+        );
+    }
+
+    #[test]
+    fn vector_engine_audio_success_codes_accept_numeric_and_string_values() {
+        for code in [
+            Value::String("success".to_string()),
+            Value::String("200".to_string()),
+            Value::String("0".to_string()),
+            Value::from(200),
+            Value::from(0),
+        ] {
+            assert!(is_success_response_code(&code), "{code}");
+        }
+
+        assert!(!is_success_response_code(&Value::String(
+            "invalid_request".to_string()
+        )));
+    }
+
+    #[test]
+    fn submit_task_id_extracts_suno_data_string_and_nested_ids() {
+        assert_eq!(
+            extract_submit_task_id(&serde_json::json!({
+                "code": 200,
+                "data": "suno-task-1"
+            })),
+            Some("suno-task-1".to_string())
+        );
+        assert_eq!(
+            extract_submit_task_id(&serde_json::json!({
+                "code": 200,
+                "data": {
+                    "id": "suno-task-2"
+                }
+            })),
+            Some("suno-task-2".to_string())
+        );
+        assert_eq!(
+            extract_submit_task_id(&serde_json::json!({
+                "taskId": "legacy-task-1"
+            })),
+            Some("legacy-task-1".to_string())
+        );
+    }
+
+    #[test]
+    fn suno_clip_ids_without_wav_url_keep_task_pending() {
+        assert!(should_wait_for_suno_wav_audio(
+            "completed",
+            true,
+            &Vec::new()
+        ));
+        assert!(!should_wait_for_suno_wav_audio("failed", true, &Vec::new()));
+        assert!(!should_wait_for_suno_wav_audio(
+            "completed",
+            true,
+            &["https://cdn.example.test/audio.wav".to_string()]
+        ));
+    }
+
+    #[test]
+    fn suno_wav_probe_error_keeps_completed_task_pending() {
+        let status = resolve_suno_status_after_wav_probe(
+            "completed",
+            true,
+            &Vec::new(),
+            Some(AudioError::upstream(
+                "获取 Suno 音效 wav 失败",
+                502,
+                r#"{"message":"wav not ready"}"#,
+            )),
+        );
+
+        assert_eq!(status.as_deref(), Some("processing"));
+    }
+}
diff --git a/server-rs/crates/platform-audio/src/lib.rs b/server-rs/crates/platform-audio/src/lib.rs
index 4d9235efb..a686612a7 100644
--- a/server-rs/crates/platform-audio/src/lib.rs
+++ b/server-rs/crates/platform-audio/src/lib.rs
@@ -8,7 +8,8 @@ mod types;
 
 pub use client::{
     build_vector_engine_audio_http_client, resolve_audio_task_download_urls,
-    submit_background_music_task, submit_sound_effect_task,
+    submit_background_music_task, submit_editor_background_music_task,
+    submit_editor_sound_effect_task, submit_sound_effect_task,
 };
 pub use download::{audio_mime_to_extension, download_generated_audio, normalize_audio_mime_type};
 pub use error::{AudioError, AudioStatusHint};
@@ -16,7 +17,8 @@ pub use persist::{
     GeneratedAudioPersistInput, GeneratedAudioPersistTarget, prepare_generated_audio_put_request,
 };
 pub use request::{
-    build_background_music_task_body, build_sound_effect_task_body, normalize_limited_text,
+    build_background_music_task_body, build_editor_background_music_task_body,
+    build_editor_sound_effect_task_body, build_sound_effect_task_body, normalize_limited_text,
     normalize_limited_text_allow_empty, normalize_optional_text,
 };
 pub use response::{
@@ -24,9 +26,10 @@ pub use response::{
 };
 pub use types::{
     AudioTaskKind, AudioTaskResponse, BackgroundMusicTaskRequest,
-    DEFAULT_SOUND_EFFECT_DURATION_SECONDS, DownloadedAudio, MAX_GENERATED_AUDIO_BYTES,
-    SUNO_DEFAULT_MODEL, SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS, SUNO_TITLE_MAX_CHARS,
-    SoundEffectTaskRequest, VECTOR_ENGINE_PROVIDER, VECTOR_ENGINE_SUNO_PROVIDER,
-    VECTOR_ENGINE_VIDU_PROVIDER, VIDU_AUDIO_MODEL, VIDU_PROMPT_MAX_CHARS,
-    VectorEngineAudioSettings,
+    DEFAULT_SOUND_EFFECT_DURATION_SECONDS, DownloadedAudio, EditorBackgroundMusicTaskRequest,
+    EditorSoundEffectTaskRequest, MAX_GENERATED_AUDIO_BYTES, SUNO_DEFAULT_MODEL,
+    SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS, SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS,
+    SUNO_TITLE_MAX_CHARS, SoundEffectTaskRequest, VECTOR_ENGINE_PROVIDER,
+    VECTOR_ENGINE_SUNO_PROVIDER, VECTOR_ENGINE_VIDU_PROVIDER, VIDU_AUDIO_MODEL,
+    VIDU_PROMPT_MAX_CHARS, VectorEngineAudioSettings,
 };
diff --git a/server-rs/crates/platform-audio/src/request.rs b/server-rs/crates/platform-audio/src/request.rs
index ea864d872..2ecc70265 100644
--- a/server-rs/crates/platform-audio/src/request.rs
+++ b/server-rs/crates/platform-audio/src/request.rs
@@ -1,9 +1,10 @@
 use serde_json::{Map, Value, json};
 
 use crate::{
-    AudioError, BackgroundMusicTaskRequest, SUNO_DEFAULT_MODEL, SUNO_PROMPT_MAX_CHARS,
-    SUNO_TAGS_MAX_CHARS, SUNO_TITLE_MAX_CHARS, SoundEffectTaskRequest, VIDU_AUDIO_MODEL,
-    VIDU_PROMPT_MAX_CHARS,
+    AudioError, BackgroundMusicTaskRequest, EditorBackgroundMusicTaskRequest,
+    EditorSoundEffectTaskRequest, SUNO_DEFAULT_MODEL, SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS,
+    SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS, SUNO_TITLE_MAX_CHARS, SoundEffectTaskRequest,
+    VIDU_AUDIO_MODEL, VIDU_PROMPT_MAX_CHARS,
 };
 
 pub fn build_background_music_task_body(
@@ -38,14 +39,63 @@ pub fn build_background_music_task_body(
 
 pub fn build_sound_effect_task_body(request: SoundEffectTaskRequest) -> Result<Value, AudioError> {
     let prompt = normalize_limited_text(&request.prompt, "prompt", VIDU_PROMPT_MAX_CHARS)?;
-    let duration = request.duration.clamp(2, 10);
+    if !(2..=10).contains(&request.duration) {
+        return Err(AudioError::invalid_request("duration 必须在 2-10 秒之间"));
+    }
     let mut body = Map::from_iter([
         (
             "model".to_string(),
             Value::String(VIDU_AUDIO_MODEL.to_string()),
         ),
-        ("prompt".to_string(), Value::String(prompt)),
-        ("duration".to_string(), json!(duration)),
+        ("prompt".to_string(), Value::String(prompt.clone())),
+        // 中文注释：VectorEngine Apifox 当前仍写 prompt，但线上 Vidu 网关曾返回
+        // missing field sound；同时发送 sound 作为同义字段，兼容网关实际反序列化。
+        ("sound".to_string(), Value::String(prompt)),
+        ("duration".to_string(), json!(request.duration)),
+    ]);
+    if let Some(seed) = request.seed {
+        body.insert("seed".to_string(), json!(seed));
+    }
+    Ok(Value::Object(body))
+}
+
+pub fn build_editor_background_music_task_body(
+    request: EditorBackgroundMusicTaskRequest,
+) -> Result<Value, AudioError> {
+    let prompt = normalize_limited_text(
+        &request.gpt_description_prompt,
+        "gpt_description_prompt",
+        SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS,
+    )?;
+    let model = normalize_optional_text(request.model.as_deref())
+        .unwrap_or_else(|| SUNO_DEFAULT_MODEL.to_string());
+    Ok(json!({
+        "mv": model,
+        "gpt_description_prompt": prompt,
+        "make_instrumental": request.make_instrumental,
+    }))
+}
+
+pub fn build_editor_sound_effect_task_body(
+    request: EditorSoundEffectTaskRequest,
+) -> Result<Value, AudioError> {
+    let prompt = normalize_limited_text(&request.prompt, "prompt", VIDU_PROMPT_MAX_CHARS)?;
+    if !(2..=10).contains(&request.duration) {
+        return Err(AudioError::invalid_request("duration 必须在 2-10 秒之间"));
+    }
+    let model = normalize_optional_text(request.model.as_deref())
+        .unwrap_or_else(|| VIDU_AUDIO_MODEL.to_string());
+    if model != VIDU_AUDIO_MODEL {
+        return Err(AudioError::invalid_request(
+            "编辑器音效暂只支持 Vidu audio1.0 模型",
+        ));
+    }
+    let mut body = Map::from_iter([
+        ("model".to_string(), Value::String(model)),
+        ("prompt".to_string(), Value::String(prompt.clone())),
+        // 中文注释：同上，编辑器音效也必须带 sound，避免上游按 sound 字段解析时报缺字段。
+        ("sound".to_string(), Value::String(prompt)),
+        ("duration".to_string(), json!(request.duration)),
     ]);
     if let Some(seed) = request.seed {
         body.insert("seed".to_string(), json!(seed));
diff --git a/server-rs/crates/platform-audio/src/response.rs b/server-rs/crates/platform-audio/src/response.rs
index 554cad847..c3874d296 100644
--- a/server-rs/crates/platform-audio/src/response.rs
+++ b/server-rs/crates/platform-audio/src/response.rs
@@ -37,6 +37,21 @@ pub fn extract_audio_urls(payload: &Value) -> Vec<String> {
     deduped
 }
 
+pub(crate) fn extract_suno_clip_ids(payload: &Value) -> Vec<String> {
+    let mut clip_ids = Vec::new();
+    if let Some(data) = payload.get("data") {
+        collect_suno_clip_ids_from_data(data, &mut clip_ids);
+    }
+
+    let mut deduped = Vec::new();
+    for clip_id in clip_ids {
+        if !deduped.contains(&clip_id) {
+            deduped.push(clip_id);
+        }
+    }
+    deduped
+}
+
 pub(crate) fn find_first_string_by_key(value: &Value, target_key: &str) -> Option<String> {
     match value {
         Value::Object(object) => {
@@ -67,6 +82,34 @@ pub(crate) fn extract_string_by_path(value: &Value, path: &[&str]) -> Option<Str
     current.as_str().map(str::trim).map(ToOwned::to_owned)
 }
 
+fn collect_suno_clip_ids_from_data(value: &Value, output: &mut Vec<String>) {
+    match value {
+        Value::Object(object) => {
+            for (key, value) in object {
+                // 中文注释：对象里的普通状态 / 任务字段不能按裸字符串当作 clip id，只接受明确的音频 id 字段。
+                if let Some(raw) = value.as_str()
+                    && looks_like_suno_clip_id_key(key)
+                    && is_plausible_suno_clip_id(raw)
+                {
+                    output.push(raw.trim().to_string());
+                }
+                if value.is_object() || value.is_array() {
+                    collect_suno_clip_ids_from_data(value, output);
+                }
+            }
+        }
+        Value::Array(items) => {
+            for item in items {
+                collect_suno_clip_ids_from_data(item, output);
+            }
+        }
+        Value::String(raw) if is_plausible_suno_clip_id(raw) => {
+            output.push(raw.trim().to_string());
+        }
+        _ => {}
+    }
+}
+
 fn collect_audio_url_strings(value: &Value, output: &mut Vec<String>) {
     match value {
         Value::Object(object) => {
@@ -92,6 +135,19 @@ fn collect_audio_url_strings(value: &Value, output: &mut Vec<String>) {
     }
 }
 
+fn looks_like_suno_clip_id_key(key: &str) -> bool {
+    let normalized = key.trim().to_ascii_lowercase().replace(['_', '-'], "");
+    matches!(normalized.as_str(), "id" | "clipid" | "audioid" | "songid")
+}
+
+fn is_plausible_suno_clip_id(value: &str) -> bool {
+    let value = value.trim();
+    !value.is_empty()
+        && value.len() <= 180
+        && !looks_like_http_url(value)
+        && !value.chars().any(char::is_whitespace)
+}
+
 fn looks_like_audio_url_key(key: &str) -> bool {
     let normalized = key.trim().to_ascii_lowercase();
     normalized.contains("audio")
@@ -123,3 +179,44 @@ fn looks_like_audio_url(value: &str) -> bool {
         || value.ends_with(".webm")
         || value.ends_with(".flac")
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn extracts_suno_clip_ids_from_object_or_array_data() {
+        let payload = json!({
+            "code": "success",
+            "data": [
+                { "id": "clip-a", "status": "complete" },
+                { "clip_id": "clip-b", "audio_url": "" },
+                { "task_id": "task-should-not-be-treated-as-clip" },
+                { "nested": { "audioId": "clip-c" } }
+            ]
+        });
+
+        assert_eq!(
+            extract_suno_clip_ids(&payload),
+            vec![
+                "clip-a".to_string(),
+                "clip-b".to_string(),
+                "clip-c".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn extracts_suno_clip_id_from_string_data() {
+        let payload = json!({
+            "code": 0,
+            "data": "clip-only"
+        });
+
+        assert_eq!(
+            extract_suno_clip_ids(&payload),
+            vec!["clip-only".to_string()]
+        );
+    }
+}
diff --git a/server-rs/crates/platform-audio/src/types.rs b/server-rs/crates/platform-audio/src/types.rs
index b23faa1bd..18760894c 100644
--- a/server-rs/crates/platform-audio/src/types.rs
+++ b/server-rs/crates/platform-audio/src/types.rs
@@ -2,6 +2,7 @@
 pub enum AudioTaskKind {
     BackgroundMusic,
     SoundEffect,
+    SunoSoundEffect,
 }
 
 impl AudioTaskKind {
@@ -9,6 +10,7 @@ impl AudioTaskKind {
         match self {
             Self::BackgroundMusic => VECTOR_ENGINE_SUNO_PROVIDER,
             Self::SoundEffect => VECTOR_ENGINE_VIDU_PROVIDER,
+            Self::SunoSoundEffect => VECTOR_ENGINE_SUNO_PROVIDER,
         }
     }
 
@@ -16,6 +18,7 @@ impl AudioTaskKind {
         match self {
             Self::BackgroundMusic => "/suno/submit/music",
             Self::SoundEffect => "/ent/v2/text2audio",
+            Self::SunoSoundEffect => "/suno/submit/music",
         }
     }
 
@@ -25,6 +28,7 @@ impl AudioTaskKind {
             Self::SoundEffect => {
                 format!("/ent/v2/tasks/{}/creations", urlencoding::encode(task_id))
             }
+            Self::SunoSoundEffect => format!("/suno/fetch/{}", urlencoding::encode(task_id)),
         }
     }
 
@@ -32,6 +36,7 @@ impl AudioTaskKind {
         match self {
             Self::BackgroundMusic => "background-music",
             Self::SoundEffect => "sound-effect",
+            Self::SunoSoundEffect => "sound-effect",
         }
     }
 }
@@ -52,6 +57,21 @@ pub struct SoundEffectTaskRequest {
     pub seed: Option<u64>,
 }
 
+#[derive(Clone, Debug)]
+pub struct EditorBackgroundMusicTaskRequest {
+    pub gpt_description_prompt: String,
+    pub make_instrumental: bool,
+    pub model: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub struct EditorSoundEffectTaskRequest {
+    pub prompt: String,
+    pub duration: u8,
+    pub seed: Option<u64>,
+    pub model: Option<String>,
+}
+
 #[derive(Clone, Debug)]
 pub struct AudioTaskResponse {
     pub kind: AudioTaskKind,
@@ -77,9 +97,10 @@ pub struct DownloadedAudio {
 pub const VECTOR_ENGINE_PROVIDER: &str = "vector-engine";
 pub const VECTOR_ENGINE_SUNO_PROVIDER: &str = "vector-engine-suno";
 pub const VECTOR_ENGINE_VIDU_PROVIDER: &str = "vector-engine-vidu";
-pub const SUNO_DEFAULT_MODEL: &str = "chirp-v4";
+pub const SUNO_DEFAULT_MODEL: &str = "chirp-v5";
 pub const VIDU_AUDIO_MODEL: &str = "audio1.0";
 pub const SUNO_PROMPT_MAX_CHARS: usize = 5_000;
+pub const SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS: usize = 200;
 pub const SUNO_TITLE_MAX_CHARS: usize = 80;
 pub const SUNO_TAGS_MAX_CHARS: usize = 160;
 pub const VIDU_PROMPT_MAX_CHARS: usize = 1_500;
diff --git a/server-rs/crates/platform-audio/tests/vector_engine_audio.rs b/server-rs/crates/platform-audio/tests/vector_engine_audio.rs
index 179daf474..bcdee944d 100644
--- a/server-rs/crates/platform-audio/tests/vector_engine_audio.rs
+++ b/server-rs/crates/platform-audio/tests/vector_engine_audio.rs
@@ -1,8 +1,10 @@
 use platform_audio::{
-    AudioTaskKind, BackgroundMusicTaskRequest, SUNO_DEFAULT_MODEL, VIDU_PROMPT_MAX_CHARS,
-    audio_mime_to_extension, build_background_music_task_body, build_sound_effect_task_body,
-    extract_audio_urls, is_failed_task_status, is_pending_task_status, normalize_audio_mime_type,
-    normalize_task_status,
+    AudioTaskKind, BackgroundMusicTaskRequest, EditorBackgroundMusicTaskRequest,
+    EditorSoundEffectTaskRequest, SUNO_DEFAULT_MODEL, VIDU_AUDIO_MODEL, VIDU_PROMPT_MAX_CHARS,
+    audio_mime_to_extension, build_background_music_task_body,
+    build_editor_background_music_task_body, build_editor_sound_effect_task_body,
+    build_sound_effect_task_body, extract_audio_urls, is_failed_task_status,
+    is_pending_task_status, normalize_audio_mime_type, normalize_task_status,
 };
 use serde_json::json;
 
@@ -82,3 +84,126 @@ fn sound_effect_request_rejects_overlong_prompt() {
 
     assert!(error.message().contains("prompt 超过"));
 }
+
+#[test]
+fn editor_background_music_request_body_uses_gpt_description_prompt_and_instrumental() {
+    let body = build_editor_background_music_task_body(EditorBackgroundMusicTaskRequest {
+        gpt_description_prompt: "  轻快森林冒险背景音乐  ".to_string(),
+        make_instrumental: true,
+        model: None,
+    })
+    .expect("editor background music body should be valid");
+
+    assert_eq!(body["mv"], SUNO_DEFAULT_MODEL);
+    assert_eq!(body["gpt_description_prompt"], "轻快森林冒险背景音乐");
+    assert_eq!(body["make_instrumental"], true);
+    assert!(body.get("prompt").is_none());
+}
+
+#[test]
+fn editor_background_music_request_body_normalizes_explicit_model() {
+    let body = build_editor_background_music_task_body(EditorBackgroundMusicTaskRequest {
+        gpt_description_prompt: "  轻快森林冒险背景音乐  ".to_string(),
+        make_instrumental: true,
+        model: Some(" chirp-v5-5 ".to_string()),
+    })
+    .expect("editor background music body should be valid");
+
+    assert_eq!(body["mv"], "chirp-v5-5");
+    assert_eq!(body["gpt_description_prompt"], "轻快森林冒险背景音乐");
+    assert_eq!(body["make_instrumental"], true);
+}
+
+#[test]
+fn editor_background_music_request_body_rejects_overlong_gpt_description_prompt() {
+    let error = build_editor_background_music_task_body(EditorBackgroundMusicTaskRequest {
+        gpt_description_prompt: "乐".repeat(201),
+        make_instrumental: true,
+        model: None,
+    })
+    .expect_err("Apifox limits gpt_description_prompt to 200 chars");
+
+    assert!(error.message().contains("gpt_description_prompt 超过"));
+}
+
+#[test]
+fn vidu_sound_effect_request_body_uses_text2audio_contract() {
+    let body = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest {
+        prompt: "  金币掉落叮当声  ".to_string(),
+        duration: 5,
+        seed: None,
+    })
+    .expect("Vidu sound effect body should be valid");
+
+    assert_eq!(
+        AudioTaskKind::SoundEffect.submit_path(),
+        "/ent/v2/text2audio"
+    );
+    assert_eq!(AudioTaskKind::SoundEffect.provider(), "vector-engine-vidu");
+    assert_eq!(body["model"], VIDU_AUDIO_MODEL);
+    assert_eq!(body["prompt"], "金币掉落叮当声");
+    assert_eq!(body["sound"], "金币掉落叮当声");
+    assert_eq!(body["duration"], 5);
+    assert!(body.get("mv").is_none());
+    assert!(body.get("task").is_none());
+    assert!(body.get("metadata_params").is_none());
+}
+
+#[test]
+fn vidu_sound_effect_request_body_rejects_duration_outside_vidu_range_and_keeps_seed() {
+    let body = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest {
+        prompt: "按钮确认短促音".to_string(),
+        duration: 2,
+        seed: Some(42),
+    })
+    .expect("Vidu 2 second duration should be accepted");
+    assert_eq!(body["duration"], 2);
+    assert_eq!(body["seed"], 42);
+
+    for duration in [1, 11] {
+        let error = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest {
+            prompt: "循环环境音".to_string(),
+            duration,
+            seed: None,
+        })
+        .expect_err("duration outside Vidu 2-10 seconds should fail");
+        assert!(error.message().contains("duration"));
+    }
+}
+
+#[test]
+fn editor_sound_effect_request_body_uses_vidu_text2audio_contract() {
+    let body = build_editor_sound_effect_task_body(EditorSoundEffectTaskRequest {
+        prompt: "  金币掉落叮当声  ".to_string(),
+        duration: 7,
+        seed: Some(42),
+        model: Some(VIDU_AUDIO_MODEL.to_string()),
+    })
+    .expect("editor sound effect should use Vidu body");
+
+    assert_eq!(body["model"], VIDU_AUDIO_MODEL);
+    assert_eq!(body["prompt"], "金币掉落叮当声");
+    assert_eq!(body["sound"], "金币掉落叮当声");
+    assert_eq!(body["duration"], 7);
+    assert_eq!(body["seed"], 42);
+    assert!(body.get("mv").is_none());
+    assert!(body.get("task").is_none());
+    assert!(body.get("metadata_params").is_none());
+    assert!(body.get("type").is_none());
+    assert!(body.get("tempo").is_none());
+}
+
+#[test]
+fn editor_sound_effect_request_body_rejects_duration_outside_vidu_range() {
+    for duration in [1, 11] {
+        let error = build_editor_sound_effect_task_body(EditorSoundEffectTaskRequest {
+            prompt: "按钮确认短促音".to_string(),
+            duration,
+            seed: None,
+            model: None,
+        })
+        .expect_err("duration outside Vidu 2-10 seconds should fail");
+
+        assert!(error.message().contains("duration"));
+    }
+}
diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs
index ac23daf0d..55b4b589f 100644
--- a/server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs
+++ b/server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs
@@ -3,6 +3,7 @@ use super::color::{
     GENERATED_ASSET_SHEET_HARD_GREEN_SCREEN_SCORE, clamp_generated_asset_sheet_unit,
     compute_generated_asset_sheet_green_screen_score,
     compute_generated_asset_sheet_key_color_score,
+    compute_generated_asset_sheet_muted_green_screen_score,
     compute_generated_asset_sheet_white_screen_score,
     is_generated_asset_sheet_soft_green_matte_pixel, lerp_generated_asset_sheet_channel,
     touches_generated_asset_sheet_background_mask,
@@ -38,6 +39,7 @@ pub struct GeneratedAssetSheetAlphaOptions {
     pub key_color: GeneratedAssetSheetKeyColor,
     pub remove_near_white_background: bool,
     pub remove_disconnected_hard_key_background: bool,
+    pub remove_muted_green_screen_background: bool,
     // 中文注释：检测并清除被主体包围、不与画布四边连通的品红镂空区域。
     // 仅对独立连通域整体判定，通过 min_pixels 过滤微小噪点。
     pub detect_internal_holes: bool,
@@ -50,6 +52,7 @@ impl GeneratedAssetSheetAlphaOptions {
             key_color: GeneratedAssetSheetKeyColor::GREEN_SCREEN,
             remove_near_white_background: true,
             remove_disconnected_hard_key_background: true,
+            remove_muted_green_screen_background: false,
             detect_internal_holes: false,
             internal_hole_min_pixels: 0,
         }
@@ -60,6 +63,7 @@ impl GeneratedAssetSheetAlphaOptions {
             key_color: GeneratedAssetSheetKeyColor::MAGENTA_SCREEN,
             remove_near_white_background: false,
             remove_disconnected_hard_key_background: false,
+            remove_muted_green_screen_background: false,
             detect_internal_holes: true,
             internal_hole_min_pixels: 16,
         }
@@ -108,6 +112,7 @@ fn remove_generated_asset_sheet_green_screen_background(
     }
 
     let mut key_scores = vec![0.0f32; pixel_count];
+    let mut background_key_scores = vec![0.0f32; pixel_count];
     let mut white_scores = vec![0.0f32; pixel_count];
     let mut background_hints = vec![0.0f32; pixel_count];
     let mut background_mask = vec![0u8; pixel_count];
@@ -120,8 +125,10 @@ fn remove_generated_asset_sheet_green_screen_background(
         let green = pixels[offset + 1];
         let blue = pixels[offset + 2];
         let alpha = pixels[offset + 3];
-        let key_score =
-            compute_generated_asset_sheet_key_score([red, green, blue, alpha], options.key_color);
+        let pixel = [red, green, blue, alpha];
+        let key_score = compute_generated_asset_sheet_key_score(pixel, options.key_color);
+        let background_key_score =
+            compute_generated_asset_sheet_background_key_score(pixel, options);
         let white_score = if options.remove_near_white_background {
             compute_generated_asset_sheet_white_screen_score([red, green, blue, alpha])
         } else {
@@ -131,27 +138,31 @@ fn remove_generated_asset_sheet_green_screen_background(
             clamp_generated_asset_sheet_unit((56.0 - alpha as f32) / 56.0) * 0.75;
 
         key_scores[pixel_index] = key_score;
+        background_key_scores[pixel_index] = background_key_score;
         white_scores[pixel_index] = white_score;
-        background_hints[pixel_index] = key_score.max(white_score).max(transparency_hint);
+        background_hints[pixel_index] =
+            background_key_score.max(white_score).max(transparency_hint);
     }
 
-    let seed_background_pixel =
-        |pixel_index: usize, background_mask: &mut [u8], queue: &mut Vec<usize>| {
-            if background_mask[pixel_index] != 0 {
-                return;
-            }
-            let alpha = pixels[pixel_index * 4 + 3];
-            let strong_candidate = alpha < 40
-                || key_scores[pixel_index] >= GENERATED_ASSET_SHEET_HARD_GREEN_SCREEN_SCORE
-                || (alpha < 224
-                    && key_scores[pixel_index] > GENERATED_ASSET_SHEET_GREEN_SCREEN_MIN_SCORE)
-                || (options.remove_near_white_background && white_scores[pixel_index] > 0.32);
-            if !strong_candidate {
-                return;
-            }
-            background_mask[pixel_index] = 1;
-            queue.push(pixel_index);
-        };
+    let seed_background_pixel = |pixel_index: usize,
+                                 background_mask: &mut [u8],
+                                 queue: &mut Vec<usize>| {
+        if background_mask[pixel_index] != 0 {
+            return;
+        }
+        let alpha = pixels[pixel_index * 4 + 3];
+        let strong_candidate = alpha < 40
+            || background_key_scores[pixel_index] >= GENERATED_ASSET_SHEET_HARD_GREEN_SCREEN_SCORE
+            || (alpha < 224
+                && background_key_scores[pixel_index]
+                    > GENERATED_ASSET_SHEET_GREEN_SCREEN_MIN_SCORE)
+            || (options.remove_near_white_background && white_scores[pixel_index] > 0.32);
+        if !strong_candidate {
+            return;
+        }
+        background_mask[pixel_index] = 1;
+        queue.push(pixel_index);
+    };
 
     for x in 0..width {
         seed_background_pixel(x, &mut background_mask, &mut queue);
@@ -193,7 +204,7 @@ fn remove_generated_asset_sheet_green_screen_background(
             }
             let next_offset = next_pixel_index * 4;
             let alpha = pixels[next_offset + 3];
-            let key_score = key_scores[next_pixel_index];
+            let key_score = background_key_scores[next_pixel_index];
             let white_score = white_scores[next_pixel_index];
             let hint = background_hints[next_pixel_index];
             let reachable_soft_edge = hint > 0.08
@@ -253,15 +264,28 @@ fn remove_generated_asset_sheet_green_screen_background(
 
                 let x = pixel_index % width;
                 let y = pixel_index / width;
-                if x == 0 || x == width.saturating_sub(1) || y == 0 || y == height.saturating_sub(1) {
+                if x == 0 || x == width.saturating_sub(1) || y == 0 || y == height.saturating_sub(1)
+                {
                     touches_border = true;
                 }
 
                 let neighbors = [
                     if x > 0 { Some(pixel_index - 1) } else { None },
-                    if x + 1 < width { Some(pixel_index + 1) } else { None },
-                    if y > 0 { Some(pixel_index - width) } else { None },
-                    if y + 1 < height { Some(pixel_index + width) } else { None },
+                    if x + 1 < width {
+                        Some(pixel_index + 1)
+                    } else {
+                        None
+                    },
+                    if y > 0 {
+                        Some(pixel_index - width)
+                    } else {
+                        None
+                    },
+                    if y + 1 < height {
+                        Some(pixel_index + width)
+                    } else {
+                        None
+                    },
                 ];
 
                 for next in neighbors.into_iter().flatten() {
@@ -301,7 +325,7 @@ fn remove_generated_asset_sheet_green_screen_background(
                     pixels[offset + 2],
                     pixels[offset + 3],
                 ];
-                let key_score = key_scores[pixel_index];
+                let key_score = background_key_scores[pixel_index];
                 let white_score = white_scores[pixel_index];
                 if !is_generated_asset_sheet_soft_key_matte_pixel(
                     pixel,
@@ -340,7 +364,7 @@ fn remove_generated_asset_sheet_green_screen_background(
                     continue;
                 }
                 let alpha = pixels[pixel_index * 4 + 3];
-                let key_score = key_scores[pixel_index];
+                let key_score = background_key_scores[pixel_index];
                 let white_score = white_scores[pixel_index];
                 let hint = background_hints[pixel_index];
                 let soft_matte_candidate = alpha < 224
@@ -594,6 +618,20 @@ fn compute_generated_asset_sheet_key_score(
     )
 }
 
+fn compute_generated_asset_sheet_background_key_score(
+    pixel: [u8; 4],
+    options: GeneratedAssetSheetAlphaOptions,
+) -> f32 {
+    let key_score = compute_generated_asset_sheet_key_score(pixel, options.key_color);
+    if options.key_color.is_green_screen() && options.remove_muted_green_screen_background {
+        key_score.max(compute_generated_asset_sheet_muted_green_screen_score(
+            pixel,
+        ))
+    } else {
+        key_score
+    }
+}
+
 fn is_generated_asset_sheet_soft_key_matte_pixel(
     pixel: [u8; 4],
     key_score: f32,
diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/color.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/color.rs
index ecd5e2c8a..f555c81f9 100644
--- a/server-rs/crates/platform-image/src/generated_asset_sheets/color.rs
+++ b/server-rs/crates/platform-image/src/generated_asset_sheets/color.rs
@@ -139,6 +139,30 @@ pub(super) fn compute_generated_asset_sheet_green_screen_score(pixel: [u8; 4]) -
         .clamp(0.0, 1.0)
 }
 
+pub(super) fn compute_generated_asset_sheet_muted_green_screen_score(pixel: [u8; 4]) -> f32 {
+    if pixel[3] == 0 {
+        return 1.0;
+    }
+
+    let red = pixel[0] as f32;
+    let green = pixel[1] as f32;
+    let blue = pixel[2] as f32;
+    let red_lead = green - red;
+    let blue_lead = green - blue;
+    let chroma = green - red.min(blue);
+    if green < 76.0 || red_lead <= 10.0 || blue_lead <= 10.0 || chroma < 18.0 {
+        return 0.0;
+    }
+
+    // 中文注释：生成模型偶尔会把标准 #00FF00 绿幕压成暗绿/灰绿边缘；
+    // 对这类明确偏绿的暗背景直接给到硬 key 分，便于边缘洪泛起步。
+    (0.82
+        + ((green - 76.0) / 72.0).clamp(0.0, 1.0) * 0.06
+        + (red_lead.min(blue_lead) - 10.0).clamp(0.0, 48.0) / 48.0 * 0.08
+        + ((chroma - 18.0) / 60.0).clamp(0.0, 1.0) * 0.04)
+        .clamp(0.0, 1.0)
+}
+
 pub(super) fn compute_generated_asset_sheet_key_color_score(
     pixel: [u8; 4],
     key_color: [u8; 3],
diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs
index fa55105eb..8c65326cd 100644
--- a/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs
+++ b/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs
@@ -16,7 +16,10 @@ pub use persist::{
 };
 pub use prompt::{GeneratedAssetSheetPromptInput, build_generated_asset_sheet_prompt};
 pub use sheet::{
-    GeneratedAssetSheetSliceImage, crop_generated_asset_sheet_view_edge_matte,
+    GeneratedAssetSheetConnectedIcon, GeneratedAssetSheetSliceImage,
+    crop_generated_asset_sheet_view_edge_matte,
     crop_generated_asset_sheet_view_edge_matte_with_options, slice_generated_asset_sheet,
     slice_generated_asset_sheet_two_items_per_row,
+    slice_generated_icon_spritesheet_all_by_connected_components,
+    slice_generated_icon_spritesheet_by_connected_components,
 };
diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/prompt.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/prompt.rs
index 8cf6d9b75..b4ee9910a 100644
--- a/server-rs/crates/platform-image/src/generated_asset_sheets/prompt.rs
+++ b/server-rs/crates/platform-image/src/generated_asset_sheets/prompt.rs
@@ -60,6 +60,6 @@ pub fn build_generated_asset_sheet_prompt(
         .unwrap_or_else(|| format!("每个物品生成 {grid_size} 个不同视图。"));
 
     Ok(format!(
-        "生成一张1:1图片。固定生成{grid_size}行*{grid_size}列网格素材图，画面是{subject_text}。严格{grid_size}*{grid_size}均匀排布，严格按行组织：{item_rows}。{special_prompt}每个格子一个独立居中的完整素材，每格背景必须是统一纯绿色绿幕背景（高饱和亮绿色，接近 #00FF00），背景平整无纹理、无渐变、无阴影、无道具，方便后续抠成透明。素材本身不得使用与绿幕相同的纯绿色；若素材天然含绿色，必须使用更深、更黄或更蓝的绿色并用清晰描边与绿幕区分。统一柔和光照，清晰轮廓，适合直接切割成游戏2D素材。请让每个素材完整落在自己的格子中央，四周保留留白，相邻素材主体之间必须至少保留单个素材格宽度的1/4空白间距（约25%单格宽度），包含左右相邻格和上下相邻行，素材主体不得占满格子。禁止主体跨格、贴边或越界，禁止任何内容进入相邻格子影响裁剪后的效果。不要出现文字、水印、UI、边框、网格线、标签、底座、场景或其他物体。"
+        "生成一张1:1图片。固定生成{grid_size}行*{grid_size}列网格素材图，画面是{subject_text}。严格{grid_size}*{grid_size}均匀排布，严格按行组织：{item_rows}。{special_prompt}每个格子一个独立居中的完整素材，每格背景必须是统一单一纯绿色 #00FF00 / RGB(0,255,0) 绿幕背景，背景平整无纹理、无渐变、无阴影、无道具，方便后续抠成透明。素材本身不得使用与绿幕相同的纯绿色；若素材天然含绿色，必须使用更深、更黄或更蓝的绿色并用清晰描边与绿幕区分。统一柔和光照，清晰轮廓，适合直接切割成游戏2D素材。请让每个素材完整落在自己的格子中央，四周保留留白，相邻素材主体之间必须至少保留单个素材格宽度的1/4空白间距（约25%单格宽度），包含左右相邻格和上下相邻行，素材主体不得占满格子。禁止主体跨格、贴边或越界，禁止任何内容进入相邻格子影响裁剪后的效果。不要出现文字、水印、UI、边框、网格线、标签、底座、场景或其他物体。"
     ))
 }
diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs
index 740f4f43b..40c53581b 100644
--- a/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs
+++ b/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs
@@ -12,6 +12,7 @@ use super::color::{
 };
 use super::error::GeneratedAssetSheetError;
 use image::{GenericImageView, ImageFormat};
+use std::collections::BTreeMap;
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct GeneratedAssetSheetSliceImage {
@@ -132,6 +133,35 @@ pub fn slice_generated_asset_sheet_two_items_per_row(
     Ok(slices)
 }
 
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GeneratedAssetSheetConnectedIcon {
+    pub name: String,
+    pub bytes: Vec<u8>,
+    pub width: u32,
+    pub height: u32,
+}
+
+pub fn slice_generated_icon_spritesheet_by_connected_components(
+    image: &crate::DownloadedImage,
+    icon_names: &[String],
+) -> Result<Vec<GeneratedAssetSheetConnectedIcon>, GeneratedAssetSheetError> {
+    let source = image::load_from_memory(image.bytes.as_slice()).map_err(|error| {
+        GeneratedAssetSheetError::decode_image(format!("图标 spritesheet 解码失败：{error}"))
+    })?;
+    let source = apply_generated_asset_sheet_green_screen_alpha(source);
+    slice_generated_icon_spritesheet_rgba_by_connected_components(source, icon_names, false)
+}
+
+pub fn slice_generated_icon_spritesheet_all_by_connected_components(
+    image: &crate::DownloadedImage,
+) -> Result<Vec<GeneratedAssetSheetConnectedIcon>, GeneratedAssetSheetError> {
+    let source = image::load_from_memory(image.bytes.as_slice()).map_err(|error| {
+        GeneratedAssetSheetError::decode_image(format!("图标 spritesheet 解码失败：{error}"))
+    })?;
+    let source = apply_generated_asset_sheet_green_screen_alpha(source);
+    slice_generated_icon_spritesheet_rgba_by_connected_components(source, &[], true)
+}
+
 pub fn crop_generated_asset_sheet_view_edge_matte(
     image: image::DynamicImage,
 ) -> image::DynamicImage {
@@ -141,6 +171,331 @@ pub fn crop_generated_asset_sheet_view_edge_matte(
     )
 }
 
+fn slice_generated_icon_spritesheet_rgba_by_connected_components(
+    source: image::DynamicImage,
+    icon_names: &[String],
+    auto_name_all_components: bool,
+) -> Result<Vec<GeneratedAssetSheetConnectedIcon>, GeneratedAssetSheetError> {
+    let mut image = source.to_rgba8();
+    let (width, height) = image.dimensions();
+    let pixel_count = (width as usize).saturating_mul(height as usize);
+    if pixel_count == 0 {
+        return Err(GeneratedAssetSheetError::invalid_request(
+            "图标 spritesheet 尺寸为空。",
+        ));
+    }
+
+    let mut components = detect_generated_icon_components_by_alpha(&image, width, height);
+    if components.len() < icon_names.len()
+        || (auto_name_all_components && generated_icon_alpha_fill_ratio(&image) > 0.92)
+    {
+        let foreground_image =
+            build_generated_icon_spritesheet_foreground_image(&image, width, height);
+        let foreground_components =
+            detect_generated_icon_components_by_alpha(&foreground_image, width, height);
+        if !foreground_components.is_empty()
+            && (foreground_components.len() >= icon_names.len()
+                || auto_name_all_components && foreground_components.len() >= components.len())
+        {
+            image = foreground_image;
+            components = foreground_components;
+        }
+    }
+
+    components.sort_by_key(|bounds| (bounds.y0, bounds.x0));
+    let icon_names = if auto_name_all_components {
+        (1..=components.len())
+            .map(|index| format!("素材 {index}"))
+            .collect::<Vec<_>>()
+    } else {
+        icon_names.to_vec()
+    };
+    if components.len() < icon_names.len() {
+        return Err(GeneratedAssetSheetError::invalid_request(format!(
+            "图标 spritesheet 连通域数量不足：需要 {} 个，实际 {} 个。",
+            icon_names.len(),
+            components.len()
+        )));
+    }
+
+    let mut icons = Vec::with_capacity(icon_names.len());
+    for (name, bounds) in icon_names.iter().zip(components.into_iter()) {
+        let pad_x = (bounds.width() / 12).clamp(4, 16);
+        let pad_y = (bounds.height() / 12).clamp(4, 16);
+        let crop = GeneratedAssetSheetCellBounds {
+            x0: bounds.x0.saturating_sub(pad_x),
+            y0: bounds.y0.saturating_sub(pad_y),
+            x1: bounds.x1.saturating_add(pad_x).min(width),
+            y1: bounds.y1.saturating_add(pad_y).min(height),
+        };
+        let cropped =
+            image::imageops::crop_imm(&image, crop.x0, crop.y0, crop.width(), crop.height())
+                .to_image();
+        let mut cursor = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(cropped)
+            .write_to(&mut cursor, ImageFormat::Png)
+            .map_err(|error| {
+                GeneratedAssetSheetError::encode_image(format!(
+                    "图标 spritesheet 切割失败：{error}"
+                ))
+            })?;
+        icons.push(GeneratedAssetSheetConnectedIcon {
+            name: name.clone(),
+            bytes: cursor.into_inner(),
+            width: crop.width(),
+            height: crop.height(),
+        });
+    }
+
+    Ok(icons)
+}
+
+fn generated_icon_alpha_fill_ratio(image: &image::RgbaImage) -> f32 {
+    let (width, height) = image.dimensions();
+    let total = (width as usize).saturating_mul(height as usize).max(1);
+    let visible = image.pixels().filter(|pixel| pixel.0[3] > 0).count();
+    visible as f32 / total as f32
+}
+
+fn detect_generated_icon_components_by_alpha(
+    image: &image::RgbaImage,
+    width: u32,
+    height: u32,
+) -> Vec<GeneratedAssetSheetCellBounds> {
+    let pixel_count = (width as usize).saturating_mul(height as usize);
+    let mut visited = vec![false; pixel_count];
+    let mut components = Vec::<GeneratedAssetSheetCellBounds>::new();
+    for y in 0..height {
+        for x in 0..width {
+            let pixel_index = (y as usize)
+                .saturating_mul(width as usize)
+                .saturating_add(x as usize);
+            if visited[pixel_index] || image.get_pixel(x, y).0[3] == 0 {
+                continue;
+            }
+            let bounds =
+                flood_fill_generated_icon_component(image, &mut visited, width, height, x, y);
+            if bounds.area() >= 16 {
+                components.push(bounds);
+            }
+        }
+    }
+    components
+}
+
+fn build_generated_icon_spritesheet_foreground_image(
+    image: &image::RgbaImage,
+    width: u32,
+    height: u32,
+) -> image::RgbaImage {
+    let background = estimate_generated_icon_spritesheet_background_pixel(image, width, height);
+    let mut foreground = image.clone();
+    for pixel in foreground.pixels_mut() {
+        if !is_generated_asset_sheet_foreground_pixel(pixel.0, background) {
+            pixel.0[3] = 0;
+        }
+    }
+    foreground
+}
+
+fn estimate_generated_icon_spritesheet_background_pixel(
+    image: &image::RgbaImage,
+    width: u32,
+    height: u32,
+) -> [u8; 4] {
+    let mut buckets = BTreeMap::<u32, (u32, [u32; 4])>::new();
+    let mut push_pixel = |pixel: [u8; 4]| {
+        let key = ((pixel[0] as u32 / 16) << 20)
+            | ((pixel[1] as u32 / 16) << 12)
+            | ((pixel[2] as u32 / 16) << 4)
+            | (pixel[3] as u32 / 64);
+        let entry = buckets.entry(key).or_insert((0, [0, 0, 0, 0]));
+        entry.0 = entry.0.saturating_add(1);
+        entry.1[0] = entry.1[0].saturating_add(pixel[0] as u32);
+        entry.1[1] = entry.1[1].saturating_add(pixel[1] as u32);
+        entry.1[2] = entry.1[2].saturating_add(pixel[2] as u32);
+        entry.1[3] = entry.1[3].saturating_add(pixel[3] as u32);
+    };
+
+    for x in 0..width {
+        push_pixel(image.get_pixel(x, 0).0);
+        if height > 1 {
+            push_pixel(image.get_pixel(x, height - 1).0);
+        }
+    }
+    for y in 1..height.saturating_sub(1) {
+        push_pixel(image.get_pixel(0, y).0);
+        if width > 1 {
+            push_pixel(image.get_pixel(width - 1, y).0);
+        }
+    }
+
+    buckets
+        .into_values()
+        .max_by_key(|(count, _)| *count)
+        .map(|(count, sums)| {
+            let count = count.max(1);
+            [
+                (sums[0] / count) as u8,
+                (sums[1] / count) as u8,
+                (sums[2] / count) as u8,
+                (sums[3] / count) as u8,
+            ]
+        })
+        .unwrap_or([255, 255, 255, 255])
+}
+
+fn flood_fill_generated_icon_component(
+    image: &image::RgbaImage,
+    visited: &mut [bool],
+    width: u32,
+    height: u32,
+    start_x: u32,
+    start_y: u32,
+) -> GeneratedAssetSheetCellBounds {
+    let mut queue = vec![(start_x, start_y)];
+    let mut queue_index = 0usize;
+    let start_index = (start_y as usize)
+        .saturating_mul(width as usize)
+        .saturating_add(start_x as usize);
+    visited[start_index] = true;
+    let mut bounds = GeneratedAssetSheetCellBounds {
+        x0: start_x,
+        y0: start_y,
+        x1: start_x.saturating_add(1),
+        y1: start_y.saturating_add(1),
+    };
+
+    while queue_index < queue.len() {
+        let (x, y) = queue[queue_index];
+        queue_index += 1;
+        bounds.x0 = bounds.x0.min(x);
+        bounds.y0 = bounds.y0.min(y);
+        bounds.x1 = bounds.x1.max(x.saturating_add(1));
+        bounds.y1 = bounds.y1.max(y.saturating_add(1));
+
+        for next_y in y.saturating_sub(1)..=(y.saturating_add(1).min(height.saturating_sub(1))) {
+            for next_x in x.saturating_sub(1)..=(x.saturating_add(1).min(width.saturating_sub(1))) {
+                if next_x == x && next_y == y {
+                    continue;
+                }
+                let next_index = (next_y as usize)
+                    .saturating_mul(width as usize)
+                    .saturating_add(next_x as usize);
+                if visited[next_index] || image.get_pixel(next_x, next_y).0[3] == 0 {
+                    continue;
+                }
+                visited[next_index] = true;
+                queue.push((next_x, next_y));
+            }
+        }
+    }
+
+    bounds
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::{ImageBuffer, Rgba};
+
+    fn encode_png(image: image::RgbaImage) -> Vec<u8> {
+        let mut cursor = std::io::Cursor::new(Vec::new());
+        image::DynamicImage::ImageRgba8(image)
+            .write_to(&mut cursor, ImageFormat::Png)
+            .expect("png should encode");
+        cursor.into_inner()
+    }
+
+    #[test]
+    fn slices_icon_spritesheet_by_connected_components_in_reading_order() {
+        let mut sheet: image::RgbaImage = ImageBuffer::from_pixel(96, 64, Rgba([0, 255, 0, 255]));
+        for y in 10..24 {
+            for x in 12..28 {
+                sheet.put_pixel(x, y, Rgba([240, 80, 80, 255]));
+            }
+        }
+        for y in 32..46 {
+            for x in 52..70 {
+                sheet.put_pixel(x, y, Rgba([80, 120, 240, 255]));
+            }
+        }
+
+        let source = crate::DownloadedImage {
+            bytes: encode_png(sheet),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        };
+        let icons = slice_generated_icon_spritesheet_by_connected_components(
+            &source,
+            &["返回按钮".to_string(), "设置按钮".to_string()],
+        )
+        .expect("icons should slice");
+
+        assert_eq!(icons.len(), 2);
+        assert_eq!(icons[0].name, "返回按钮");
+        assert_eq!(icons[1].name, "设置按钮");
+        assert!(icons[0].width >= 16);
+        assert!(icons[0].height >= 14);
+        assert!(image::load_from_memory(icons[0].bytes.as_slice()).is_ok());
+    }
+
+    #[test]
+    fn rejects_when_connected_components_are_fewer_than_icon_names() {
+        let mut sheet: image::RgbaImage = ImageBuffer::from_pixel(48, 48, Rgba([0, 255, 0, 255]));
+        for y in 12..24 {
+            for x in 12..24 {
+                sheet.put_pixel(x, y, Rgba([240, 80, 80, 255]));
+            }
+        }
+        let source = crate::DownloadedImage {
+            bytes: encode_png(sheet),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        };
+
+        let error = slice_generated_icon_spritesheet_by_connected_components(
+            &source,
+            &["返回按钮".to_string(), "设置按钮".to_string()],
+        )
+        .expect_err("missing component should fail");
+
+        assert!(error.to_string().contains("连通域数量不足"));
+    }
+
+    #[test]
+    fn slices_all_icon_spritesheet_components_with_auto_names() {
+        let mut sheet: image::RgbaImage =
+            ImageBuffer::from_pixel(96, 64, Rgba([255, 255, 255, 255]));
+        for y in 8..24 {
+            for x in 10..28 {
+                sheet.put_pixel(x, y, Rgba([240, 80, 80, 255]));
+            }
+        }
+        for y in 34..50 {
+            for x in 56..76 {
+                sheet.put_pixel(x, y, Rgba([80, 120, 240, 255]));
+            }
+        }
+
+        let source = crate::DownloadedImage {
+            bytes: encode_png(sheet),
+            mime_type: "image/png".to_string(),
+            extension: "png".to_string(),
+        };
+        let icons = slice_generated_icon_spritesheet_all_by_connected_components(&source)
+            .expect("all icons should slice");
+
+        assert_eq!(icons.len(), 2);
+        assert_eq!(icons[0].name, "素材 1");
+        assert_eq!(icons[1].name, "素材 2");
+        let decoded = image::load_from_memory(icons[0].bytes.as_slice())
+            .expect("icon should decode")
+            .to_rgba8();
+        assert_eq!(decoded.get_pixel(0, 0).0[3], 0);
+    }
+}
+
 pub fn crop_generated_asset_sheet_view_edge_matte_with_options(
     image: image::DynamicImage,
     options: GeneratedAssetSheetAlphaOptions,
diff --git a/server-rs/crates/platform-image/src/lib.rs b/server-rs/crates/platform-image/src/lib.rs
index d341c6e36..4e7aaa896 100644
--- a/server-rs/crates/platform-image/src/lib.rs
+++ b/server-rs/crates/platform-image/src/lib.rs
@@ -7,7 +7,11 @@ pub use vector_engine::{
     PlatformImageFailureAudit, PlatformImageStatusHint, ReferenceImage,
     VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER, VectorEngineImageSettings,
     build_vector_engine_image_http_client, build_vector_engine_image_request_body,
-    create_vector_engine_image_edit, create_vector_engine_image_edit_with_references,
-    create_vector_engine_image_generation, download_remote_image, vector_engine_images_edit_url,
-    vector_engine_images_generation_url,
+    build_vector_engine_nanobanana_generate_content_request_body, create_vector_engine_image_edit,
+    create_vector_engine_image_edit_with_references,
+    create_vector_engine_image_edit_with_references_and_model,
+    create_vector_engine_image_generation, create_vector_engine_image_generation_with_model,
+    create_vector_engine_nanobanana_generate_content, download_remote_image,
+    vector_engine_images_edit_url, vector_engine_images_generation_url,
+    vector_engine_nanobanana_generate_content_url,
 };
diff --git a/server-rs/crates/platform-image/src/vector_engine/client.rs b/server-rs/crates/platform-image/src/vector_engine/client.rs
index 70754cae1..e5024124a 100644
--- a/server-rs/crates/platform-image/src/vector_engine/client.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/client.rs
@@ -13,8 +13,11 @@ use super::{
     error::PlatformImageError,
     image_source::resolve_reference_images,
     request::{
-        build_vector_engine_image_edit_request_log_params, build_vector_engine_image_request_body,
-        normalize_image_size, vector_engine_images_edit_url, vector_engine_images_generation_url,
+        build_vector_engine_image_edit_request_log_params,
+        build_vector_engine_image_request_body_with_model,
+        build_vector_engine_nanobanana_generate_content_request_body, normalize_image_size,
+        normalize_vector_engine_image_model, vector_engine_images_edit_url,
+        vector_engine_images_generation_url, vector_engine_nanobanana_generate_content_url,
     },
     response::handle_vector_engine_response,
     types::{GeneratedImages, ReferenceImage, VectorEngineImageSettings},
@@ -31,12 +34,40 @@ pub async fn create_vector_engine_image_generation(
     reference_images: &[String],
     failure_context: &str,
 ) -> Result<GeneratedImages, PlatformImageError> {
+    create_vector_engine_image_generation_with_model(
+        http_client,
+        settings,
+        GPT_IMAGE_2_MODEL,
+        prompt,
+        negative_prompt,
+        size,
+        candidate_count,
+        reference_images,
+        failure_context,
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn create_vector_engine_image_generation_with_model(
+    http_client: &reqwest::Client,
+    settings: &VectorEngineImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    size: &str,
+    candidate_count: u32,
+    reference_images: &[String],
+    failure_context: &str,
+) -> Result<GeneratedImages, PlatformImageError> {
+    let model = normalize_vector_engine_image_model(model);
     if !reference_images.is_empty() {
         let resolved_references =
             resolve_reference_images(http_client, reference_images, failure_context).await?;
-        return create_vector_engine_image_edit_with_references(
+        return create_vector_engine_image_edit_with_references_and_model(
             http_client,
             settings,
+            model,
             prompt,
             negative_prompt,
             size,
@@ -49,7 +80,8 @@ pub async fn create_vector_engine_image_generation(
 
     let request_url = vector_engine_images_generation_url(settings);
     let normalized_size = normalize_image_size(size);
-    let request_body = build_vector_engine_image_request_body(
+    let request_body = build_vector_engine_image_request_body_with_model(
+        model,
         prompt,
         negative_prompt,
         normalized_size.as_str(),
@@ -125,6 +157,7 @@ pub async fn create_vector_engine_image_generation(
         provider = VECTOR_ENGINE_PROVIDER,
         endpoint = %request_url,
         status = response_status,
+        image_model = model,
         prompt_chars = prompt.chars().count(),
         size = %normalized_size,
         reference_image_count = reference_images.len(),
@@ -149,6 +182,144 @@ pub async fn create_vector_engine_image_generation(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
+pub async fn create_vector_engine_nanobanana_generate_content(
+    http_client: &reqwest::Client,
+    settings: &VectorEngineImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    aspect_ratio: &str,
+    image_size: &str,
+    reference_images: &[ReferenceImage],
+    failure_context: &str,
+) -> Result<GeneratedImages, PlatformImageError> {
+    let model = normalize_vector_engine_image_model(model);
+    let request_url = vector_engine_nanobanana_generate_content_url(settings, model);
+    let request_body = build_vector_engine_nanobanana_generate_content_request_body(
+        prompt,
+        negative_prompt,
+        aspect_ratio,
+        image_size,
+        reference_images,
+    );
+    let reference_image_count = reference_images.iter().take(14).count();
+    let reference_image_bytes_total: usize = reference_images
+        .iter()
+        .take(14)
+        .map(|image| image.bytes.len())
+        .sum();
+    let request_params = serde_json::json!({
+        "model": model,
+        "promptChars": prompt.trim().chars().count(),
+        "negativePromptChars": negative_prompt
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(str::chars)
+            .map(Iterator::count)
+            .unwrap_or_default(),
+        "aspectRatio": aspect_ratio,
+        "imageSize": image_size,
+        "referenceImageCount": reference_image_count,
+        "referenceImageBytesTotal": reference_image_bytes_total,
+    });
+    let started_at = std::time::Instant::now();
+    let mut attempt = 1;
+    let response = loop {
+        match send_vector_engine_json_request_with_curl(
+            request_url.as_str(),
+            settings.api_key.as_str(),
+            &request_body,
+            settings.request_timeout_ms,
+        )
+        .await
+        {
+            Ok(response) => {
+                if should_retry_vector_engine_upstream_status(response.status, attempt) {
+                    retry_vector_engine_upstream_status_after_delay(
+                        "nanobanana_generate_content",
+                        request_url.as_str(),
+                        attempt,
+                        response.status,
+                        response.body.as_str(),
+                        started_at.elapsed().as_millis() as u64,
+                        Some(prompt.chars().count()),
+                        Some(reference_image_count),
+                        Some(&request_params),
+                    )
+                    .await;
+                    attempt += 1;
+                    continue;
+                }
+                break response;
+            }
+            Err(error) => {
+                if should_retry_vector_engine_curl_send_error(&error, attempt) {
+                    retry_vector_engine_send_after_delay(
+                        "nanobanana_generate_content",
+                        request_url.as_str(),
+                        "request_send",
+                        attempt,
+                        error.is_timeout(),
+                        error.is_connect() || error.is_transient_transport(),
+                        true,
+                        false,
+                        error.to_string().as_str(),
+                        started_at.elapsed().as_millis() as u64,
+                        Some(prompt.chars().count()),
+                        Some(reference_image_count),
+                        Some(&request_params),
+                    )
+                    .await;
+                    attempt += 1;
+                    continue;
+                }
+                return Err(map_curl_error(
+                    format!("{failure_context}：创建 nanobanana2 图片生成任务失败").as_str(),
+                    request_url.as_str(),
+                    "request_send",
+                    error,
+                    started_at.elapsed().as_millis() as u64,
+                    Some(prompt.chars().count()),
+                    Some(reference_image_count),
+                    Some(&request_params),
+                ));
+            }
+        }
+    };
+    let response_status = response.status;
+    tracing::info!(
+        provider = VECTOR_ENGINE_PROVIDER,
+        endpoint = %request_url,
+        status = response_status,
+        image_model = model,
+        prompt_chars = prompt.chars().count(),
+        aspect_ratio,
+        image_size,
+        reference_image_count,
+        reference_image_bytes_total,
+        request_params = %request_params,
+        attempt,
+        elapsed_ms = started_at.elapsed().as_millis() as u64,
+        failure_context,
+        "VectorEngine nanobanana2 图片生成 HTTP 返回"
+    );
+    let response_text = response.body;
+    handle_vector_engine_response(
+        http_client,
+        request_url.as_str(),
+        response_status,
+        response_text.as_str(),
+        failure_context,
+        started_at.elapsed().as_millis() as u64,
+        Some(prompt.chars().count()),
+        Some(reference_image_count),
+        1,
+        "vector-engine-nanobanana",
+    )
+    .await
+}
+
 pub async fn create_vector_engine_image_edit(
     http_client: &reqwest::Client,
     settings: &VectorEngineImageSettings,
@@ -181,6 +352,33 @@ pub async fn create_vector_engine_image_edit_with_references(
     reference_images: &[ReferenceImage],
     failure_context: &str,
 ) -> Result<GeneratedImages, PlatformImageError> {
+    create_vector_engine_image_edit_with_references_and_model(
+        http_client,
+        settings,
+        GPT_IMAGE_2_MODEL,
+        prompt,
+        negative_prompt,
+        size,
+        candidate_count,
+        reference_images,
+        failure_context,
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn create_vector_engine_image_edit_with_references_and_model(
+    http_client: &reqwest::Client,
+    settings: &VectorEngineImageSettings,
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    size: &str,
+    candidate_count: u32,
+    reference_images: &[ReferenceImage],
+    failure_context: &str,
+) -> Result<GeneratedImages, PlatformImageError> {
+    let model = normalize_vector_engine_image_model(model);
     if reference_images.is_empty() {
         return Err(PlatformImageError::InvalidRequest {
             provider: VECTOR_ENGINE_PROVIDER,
@@ -191,6 +389,7 @@ pub async fn create_vector_engine_image_edit_with_references(
     let request_url = vector_engine_images_edit_url(settings);
     let normalized_size = normalize_image_size(size);
     let request_params = build_vector_engine_image_edit_request_log_params(
+        model,
         prompt,
         negative_prompt,
         normalized_size.as_str(),
@@ -208,7 +407,7 @@ pub async fn create_vector_engine_image_edit_with_references(
     tracing::info!(
         provider = VECTOR_ENGINE_PROVIDER,
         endpoint = %request_url,
-        image_model = GPT_IMAGE_2_MODEL,
+        image_model = model,
         size = %normalized_size,
         candidate_count = candidate_count.clamp(1, 4),
         requested_candidate_count = candidate_count,
@@ -230,6 +429,7 @@ pub async fn create_vector_engine_image_edit_with_references(
         match send_vector_engine_multipart_edit_request_with_curl(
             request_url.as_str(),
             settings.api_key.as_str(),
+            model,
             prompt,
             negative_prompt,
             normalized_size.as_str(),
diff --git a/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs b/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs
index a5c6af673..ce7dd389c 100644
--- a/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/curl_transport.rs
@@ -7,11 +7,8 @@ use curl::{
 use serde_json::Value;
 
 use super::{
-    audit::build_failure_audit,
-    constants::{GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER},
-    error::PlatformImageError,
-    request::build_prompt_with_negative,
-    types::ReferenceImage,
+    audit::build_failure_audit, constants::VECTOR_ENGINE_PROVIDER, error::PlatformImageError,
+    request::build_prompt_with_negative, types::ReferenceImage,
 };
 
 #[derive(Debug)]
@@ -115,6 +112,7 @@ pub(crate) async fn send_vector_engine_json_request_with_curl(
 pub(crate) async fn send_vector_engine_multipart_edit_request_with_curl(
     request_url: &str,
     api_key: &str,
+    model: &str,
     prompt: &str,
     negative_prompt: Option<&str>,
     normalized_size: &str,
@@ -124,6 +122,7 @@ pub(crate) async fn send_vector_engine_multipart_edit_request_with_curl(
 ) -> Result<VectorEngineCurlResponse, VectorEngineCurlError> {
     let request_url = request_url.to_string();
     let api_key = api_key.to_string();
+    let model = model.to_string();
     let prompt = prompt.to_string();
     let negative_prompt = negative_prompt.map(str::to_string);
     let normalized_size = normalized_size.to_string();
@@ -132,6 +131,7 @@ pub(crate) async fn send_vector_engine_multipart_edit_request_with_curl(
         send_multipart_edit_request_with_curl_blocking(
             request_url.as_str(),
             api_key.as_str(),
+            model.as_str(),
             prompt.as_str(),
             negative_prompt.as_deref(),
             normalized_size.as_str(),
@@ -230,6 +230,7 @@ fn send_json_request_with_curl_blocking(
 fn send_multipart_edit_request_with_curl_blocking(
     request_url: &str,
     api_key: &str,
+    model: &str,
     prompt: &str,
     negative_prompt: Option<&str>,
     normalized_size: &str,
@@ -238,9 +239,7 @@ fn send_multipart_edit_request_with_curl_blocking(
     timeout_ms: u64,
 ) -> Result<VectorEngineCurlResponse, VectorEngineCurlError> {
     let mut form = Form::new();
-    form.part("model")
-        .contents(GPT_IMAGE_2_MODEL.as_bytes())
-        .add()?;
+    form.part("model").contents(model.as_bytes()).add()?;
     form.part("prompt")
         .contents(build_prompt_with_negative(prompt, negative_prompt).as_bytes())
         .add()?;
@@ -295,7 +294,7 @@ fn perform_curl_request(mut easy: Easy) -> Result<VectorEngineCurlResponse, curl
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::vector_engine::types::ReferenceImage;
+    use crate::vector_engine::{constants::GPT_IMAGE_2_MODEL, types::ReferenceImage};
     use tokio::{
         io::{AsyncReadExt, AsyncWriteExt},
         net::TcpListener,
@@ -330,6 +329,7 @@ mod tests {
         let response = send_vector_engine_multipart_edit_request_with_curl(
             format!("{base_url}/v1/images/edits").as_str(),
             "test-key",
+            GPT_IMAGE_2_MODEL,
             "测试提示词",
             None,
             "1024x1024",
diff --git a/server-rs/crates/platform-image/src/vector_engine/mod.rs b/server-rs/crates/platform-image/src/vector_engine/mod.rs
index 4bd39b30c..f8d953e8a 100644
--- a/server-rs/crates/platform-image/src/vector_engine/mod.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/mod.rs
@@ -14,14 +14,18 @@ mod util;
 pub use audit::PlatformImageFailureAudit;
 pub use client::{
     create_vector_engine_image_edit, create_vector_engine_image_edit_with_references,
-    create_vector_engine_image_generation,
+    create_vector_engine_image_edit_with_references_and_model,
+    create_vector_engine_image_generation, create_vector_engine_image_generation_with_model,
+    create_vector_engine_nanobanana_generate_content,
 };
 pub use constants::{GPT_IMAGE_2_MODEL, VECTOR_ENGINE_GPT_IMAGE_2_MODEL, VECTOR_ENGINE_PROVIDER};
 pub use error::{PlatformImageError, PlatformImageStatusHint};
 pub use image_source::download_remote_image;
 pub use request::{
-    build_vector_engine_image_request_body, normalize_image_size, vector_engine_images_edit_url,
-    vector_engine_images_generation_url,
+    build_vector_engine_image_request_body, build_vector_engine_image_request_body_with_model,
+    build_vector_engine_nanobanana_generate_content_request_body, normalize_image_size,
+    vector_engine_images_edit_url, vector_engine_images_generation_url,
+    vector_engine_nanobanana_generate_content_url,
 };
 pub use transport::build_vector_engine_image_http_client;
 pub use types::{DownloadedImage, GeneratedImages, ReferenceImage, VectorEngineImageSettings};
diff --git a/server-rs/crates/platform-image/src/vector_engine/payload.rs b/server-rs/crates/platform-image/src/vector_engine/payload.rs
index f7b4a8e68..9f5130a62 100644
--- a/server-rs/crates/platform-image/src/vector_engine/payload.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/payload.rs
@@ -88,9 +88,48 @@ pub(super) fn extract_image_urls(payload: &Value) -> Vec<String> {
 pub(super) fn extract_b64_images(payload: &Value) -> Vec<String> {
     let mut values = Vec::new();
     collect_strings_by_key(payload, "b64_json", &mut values);
+    collect_inline_image_data(payload, &mut values);
     values
 }
 
+fn collect_inline_image_data(value: &Value, results: &mut Vec<String>) {
+    match value {
+        Value::Array(entries) => {
+            for entry in entries {
+                collect_inline_image_data(entry, results);
+            }
+        }
+        Value::Object(object) => {
+            for key in ["inlineData", "inline_data"] {
+                if let Some(Value::Object(inline_data)) = object.get(key) {
+                    let mime_type = inline_data
+                        .get("mimeType")
+                        .or_else(|| inline_data.get("mime_type"))
+                        .and_then(Value::as_str)
+                        .map(str::trim)
+                        .unwrap_or("image/png")
+                        .to_ascii_lowercase();
+                    if !mime_type.is_empty() && !mime_type.starts_with("image/") {
+                        continue;
+                    }
+                    if let Some(data) = inline_data
+                        .get("data")
+                        .and_then(Value::as_str)
+                        .map(str::trim)
+                        .filter(|value| !value.is_empty())
+                    {
+                        results.push(data.to_string());
+                    }
+                }
+            }
+            for nested_value in object.values() {
+                collect_inline_image_data(nested_value, results);
+            }
+        }
+        _ => {}
+    }
+}
+
 pub(super) fn parse_api_error_message(raw_text: &str, fallback_message: &str) -> String {
     if raw_text.trim().is_empty() {
         return fallback_message.to_string();
diff --git a/server-rs/crates/platform-image/src/vector_engine/request.rs b/server-rs/crates/platform-image/src/vector_engine/request.rs
index 656d07d78..869f4e374 100644
--- a/server-rs/crates/platform-image/src/vector_engine/request.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/request.rs
@@ -12,11 +12,27 @@ pub fn build_vector_engine_image_request_body(
     candidate_count: u32,
     _reference_images: &[String],
 ) -> Value {
+    build_vector_engine_image_request_body_with_model(
+        GPT_IMAGE_2_MODEL,
+        prompt,
+        negative_prompt,
+        size,
+        candidate_count,
+        _reference_images,
+    )
+}
+
+pub fn build_vector_engine_image_request_body_with_model(
+    model: &str,
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    size: &str,
+    candidate_count: u32,
+    _reference_images: &[String],
+) -> Value {
+    let model = normalize_vector_engine_image_model(model);
     let body = Map::from_iter([
-        (
-            "model".to_string(),
-            Value::String(GPT_IMAGE_2_MODEL.to_string()),
-        ),
+        ("model".to_string(), Value::String(model.to_string())),
         (
             "prompt".to_string(),
             Value::String(build_prompt_with_negative(prompt, negative_prompt)),
@@ -31,16 +47,97 @@ pub fn build_vector_engine_image_request_body(
     Value::Object(body)
 }
 
-pub fn normalize_image_size(size: &str) -> String {
-    match size.trim() {
-        "1024*1024" | "1024x1024" | "1:1" => "1024x1024",
-        "1280*720" | "1280x720" | "1600*900" | "1600x900" | "16:9" | "1536x1024" | "2048x1152"
-        | "2k" => "1536x1024",
-        "1024*1536" | "1024x1536" | "9:16" => "1024x1536",
-        value if !value.is_empty() => value,
-        _ => "1024x1024",
+pub fn build_vector_engine_nanobanana_generate_content_request_body(
+    prompt: &str,
+    negative_prompt: Option<&str>,
+    aspect_ratio: &str,
+    image_size: &str,
+    reference_images: &[ReferenceImage],
+) -> Value {
+    let prompt = build_prompt_with_negative(prompt, negative_prompt);
+    let mut parts = vec![json!({ "text": prompt })];
+    for reference_image in reference_images.iter().take(14) {
+        parts.push(json!({
+            "inline_data": {
+                "mime_type": reference_image.mime_type,
+                "data": base64::Engine::encode(
+                    &base64::engine::general_purpose::STANDARD,
+                    reference_image.bytes.as_slice()
+                ),
+            },
+        }));
+    }
+
+    json!({
+        "contents": [{
+            "role": "user",
+            "parts": parts,
+        }],
+        "generationConfig": {
+            "responseModalities": ["IMAGE"],
+            "imageConfig": {
+                "aspectRatio": normalize_nanobanana_aspect_ratio(aspect_ratio),
+                "imageSize": normalize_nanobanana_image_size(image_size),
+            },
+        },
+    })
+}
+
+pub fn normalize_vector_engine_image_model(model: &str) -> &str {
+    match model.trim() {
+        "" => GPT_IMAGE_2_MODEL,
+        value => value,
+    }
+}
+
+pub fn normalize_image_size(size: &str) -> String {
+    let size = size.trim();
+    match size {
+        "1:1" => "1024x1024".to_string(),
+        "16:9" | "2k" => "1536x1024".to_string(),
+        "2k-16:9" => "2048x1152".to_string(),
+        "9:16" => "1024x1536".to_string(),
+        value if is_explicit_pixel_size(value) => normalize_explicit_pixel_size(value),
+        value if !value.is_empty() => value.to_string(),
+        _ => "1024x1024".to_string(),
+    }
+}
+
+fn is_explicit_pixel_size(value: &str) -> bool {
+    let separator = if value.contains('x') { 'x' } else { '*' };
+    let Some((width, height)) = value.split_once(separator) else {
+        return false;
+    };
+    width.parse::<u32>().is_ok() && height.parse::<u32>().is_ok()
+}
+
+fn normalize_explicit_pixel_size(value: &str) -> String {
+    value.replace('*', "x")
+}
+
+fn normalize_nanobanana_aspect_ratio(aspect_ratio: &str) -> &str {
+    match aspect_ratio.trim() {
+        "2:3" => "2:3",
+        "3:2" => "3:2",
+        "3:4" => "3:4",
+        "4:3" => "4:3",
+        "4:5" => "4:5",
+        "5:4" => "5:4",
+        "9:16" => "9:16",
+        "16:9" => "16:9",
+        "21:9" => "21:9",
+        _ => "1:1",
+    }
+}
+
+fn normalize_nanobanana_image_size(image_size: &str) -> &str {
+    match image_size.trim() {
+        // 中文注释：nanobanana / Gemini 3.1 的 0.5K 在 VectorEngine 文档中要求传 512。
+        "512" | "0.5K" => "512",
+        "2K" => "2K",
+        "4K" => "4K",
+        _ => "1K",
     }
-    .to_string()
 }
 
 pub fn vector_engine_images_generation_url(settings: &VectorEngineImageSettings) -> String {
@@ -59,13 +156,30 @@ pub fn vector_engine_images_edit_url(settings: &VectorEngineImageSettings) -> St
     }
 }
 
+pub fn vector_engine_nanobanana_generate_content_url(
+    settings: &VectorEngineImageSettings,
+    model: &str,
+) -> String {
+    let base_url = settings
+        .base_url
+        .trim_end_matches("/v1")
+        .trim_end_matches('/');
+    format!(
+        "{}/v1beta/models/{}:generateContent",
+        base_url,
+        normalize_vector_engine_image_model(model)
+    )
+}
+
 pub(crate) fn build_vector_engine_image_edit_request_log_params(
+    model: &str,
     prompt: &str,
     negative_prompt: Option<&str>,
     size: &str,
     candidate_count: u32,
     reference_images: &[ReferenceImage],
 ) -> Value {
+    let model = normalize_vector_engine_image_model(model);
     let prompt = prompt.trim();
     let negative_prompt = negative_prompt
         .map(str::trim)
@@ -91,7 +205,7 @@ pub(crate) fn build_vector_engine_image_edit_request_log_params(
         .sum();
 
     json!({
-        "model": GPT_IMAGE_2_MODEL,
+        "model": model,
         "prompt": prompt,
         "negativePrompt": negative_prompt.unwrap_or_default(),
         "promptChars": prompt.chars().count(),
@@ -125,6 +239,7 @@ mod tests {
     #[test]
     fn edit_request_log_params_include_reference_image_sizes_without_secrets_or_bytes() {
         let params = build_vector_engine_image_edit_request_log_params(
+            GPT_IMAGE_2_MODEL,
             "  拼图参考图重绘  ",
             Some("  文字，水印  "),
             "1024x1024",
diff --git a/server-rs/crates/platform-image/src/vector_engine/tests.rs b/server-rs/crates/platform-image/src/vector_engine/tests.rs
index 1f1d6691f..dc9a37ea6 100644
--- a/server-rs/crates/platform-image/src/vector_engine/tests.rs
+++ b/server-rs/crates/platform-image/src/vector_engine/tests.rs
@@ -66,8 +66,10 @@ mod tests {
         assert_eq!(reference.mime_type, "image/png");
         assert_eq!(reference.bytes, b"\x89PNG\r\n\x1A\nrest");
 
-        let image = decode_generated_image_base64(BASE64_STANDARD.encode(b"\x89PNG\r\n\x1A\nrest").as_str())
-            .expect("base64 image should decode");
+        let image = decode_generated_image_base64(
+            BASE64_STANDARD.encode(b"\x89PNG\r\n\x1A\nrest").as_str(),
+        )
+        .expect("base64 image should decode");
         assert_eq!(image.extension, "png");
         assert_eq!(image.mime_type, "image/png");
         assert_eq!(image.bytes, b"\x89PNG\r\n\x1A\nrest");
@@ -121,10 +123,22 @@ mod tests {
             audit: Some(audit.clone()),
         };
 
-        assert_eq!(invalid_config.status_hint(), PlatformImageStatusHint::ServiceUnavailable);
-        assert_eq!(invalid_request.status_hint(), PlatformImageStatusHint::BadRequest);
-        assert_eq!(request_error.status_hint(), PlatformImageStatusHint::GatewayTimeout);
-        assert_eq!(upstream_timeout.status_hint(), PlatformImageStatusHint::GatewayTimeout);
+        assert_eq!(
+            invalid_config.status_hint(),
+            PlatformImageStatusHint::ServiceUnavailable
+        );
+        assert_eq!(
+            invalid_request.status_hint(),
+            PlatformImageStatusHint::BadRequest
+        );
+        assert_eq!(
+            request_error.status_hint(),
+            PlatformImageStatusHint::GatewayTimeout
+        );
+        assert_eq!(
+            upstream_timeout.status_hint(),
+            PlatformImageStatusHint::GatewayTimeout
+        );
         assert_eq!(
             PlatformImageError::MissingImage {
                 provider: VECTOR_ENGINE_PROVIDER,
@@ -137,7 +151,10 @@ mod tests {
 
         let audit_ref = upstream_timeout.audit().expect("audit should be preserved");
         assert_eq!(audit_ref.provider, VECTOR_ENGINE_PROVIDER);
-        assert_eq!(audit_ref.endpoint, "https://vector.example/v1/images/generations");
+        assert_eq!(
+            audit_ref.endpoint,
+            "https://vector.example/v1/images/generations"
+        );
         assert_eq!(audit_ref.status_code, Some(504));
         assert_eq!(audit_ref.status_class, Some("5xx"));
         assert!(audit_ref.timeout);
@@ -158,7 +175,27 @@ mod tests {
                 {"url": "https://example.com/b.png"}
             ],
             "nested": {
-                "b64_json": ["YWJj", "ZGVm"]
+                "b64_json": ["YWJj", "ZGVm"],
+                "parts": [
+                    {
+                        "inlineData": {
+                            "mimeType": "image/png",
+                            "data": "aW1hZ2UtMQ=="
+                        }
+                    },
+                    {
+                        "inline_data": {
+                            "mime_type": "image/jpeg",
+                            "data": "aW1hZ2UtMg=="
+                        }
+                    },
+                    {
+                        "inlineData": {
+                            "mimeType": "text/plain",
+                            "data": "bm90LWltYWdl"
+                        }
+                    }
+                ]
             }
         });
 
@@ -171,7 +208,12 @@ mod tests {
         );
         assert_eq!(
             extract_b64_images(&payload),
-            vec!["YWJj".to_string(), "ZGVm".to_string()]
+            vec![
+                "YWJj".to_string(),
+                "ZGVm".to_string(),
+                "aW1hZ2UtMQ==".to_string(),
+                "aW1hZ2UtMg==".to_string(),
+            ]
         );
     }
 }
diff --git a/server-rs/crates/platform-image/tests/generated_asset_sheets.rs b/server-rs/crates/platform-image/tests/generated_asset_sheets.rs
index 40a0c8f08..ff0da6413 100644
--- a/server-rs/crates/platform-image/tests/generated_asset_sheets.rs
+++ b/server-rs/crates/platform-image/tests/generated_asset_sheets.rs
@@ -144,6 +144,35 @@ fn generated_asset_sheet_green_screen_alpha_removes_green_background() {
     assert_eq!(cleaned.get_pixel(10, 10).0[3], 255);
 }
 
+#[test]
+fn generated_asset_sheet_muted_green_alpha_requires_explicit_option() {
+    let mut sheet = RgbaImage::from_pixel(20, 20, Rgba([59, 131, 67, 255]));
+    for y in 7..13 {
+        for x in 7..13 {
+            sheet.put_pixel(x, y, Rgba([220, 40, 40, 255]));
+        }
+    }
+
+    let default_cleaned =
+        apply_generated_asset_sheet_green_screen_alpha(DynamicImage::ImageRgba8(sheet.clone()))
+            .to_rgba8();
+    let muted_cleaned = apply_generated_asset_sheet_alpha_with_options(
+        DynamicImage::ImageRgba8(sheet),
+        GeneratedAssetSheetAlphaOptions {
+            remove_muted_green_screen_background: true,
+            ..GeneratedAssetSheetAlphaOptions::green_screen()
+        },
+    )
+    .to_rgba8();
+
+    assert!(
+        default_cleaned.get_pixel(0, 0).0[3] > 0,
+        "默认绿幕图集清理不应把暗绿背景直接清透明"
+    );
+    assert_eq!(muted_cleaned.get_pixel(0, 0).0[3], 0);
+    assert_eq!(muted_cleaned.get_pixel(10, 10).0[3], 255);
+}
+
 #[test]
 fn generated_asset_sheet_magenta_key_preserves_green_white_and_disconnected_key_subject() {
     let mut sheet = RgbaImage::from_pixel(28, 28, Rgba([255, 0, 255, 255]));
diff --git a/server-rs/crates/platform-image/tests/vector_engine.rs b/server-rs/crates/platform-image/tests/vector_engine.rs
index 8dadd9eb7..66c6dc0b0 100644
--- a/server-rs/crates/platform-image/tests/vector_engine.rs
+++ b/server-rs/crates/platform-image/tests/vector_engine.rs
@@ -1,8 +1,11 @@
 use platform_image::vector_engine::{
     GPT_IMAGE_2_MODEL, ReferenceImage, VECTOR_ENGINE_PROVIDER, VectorEngineImageSettings,
     build_vector_engine_image_http_client, build_vector_engine_image_request_body,
-    create_vector_engine_image_edit, create_vector_engine_image_generation,
+    build_vector_engine_image_request_body_with_model,
+    build_vector_engine_nanobanana_generate_content_request_body, create_vector_engine_image_edit,
+    create_vector_engine_image_generation, create_vector_engine_nanobanana_generate_content,
     vector_engine_images_edit_url, vector_engine_images_generation_url,
+    vector_engine_nanobanana_generate_content_url,
 };
 use std::{
     sync::{
@@ -43,6 +46,96 @@ fn vector_engine_module_exposes_provider_protocol_helpers() {
     );
 }
 
+#[test]
+fn vector_engine_keeps_explicit_publication_material_pixel_sizes() {
+    let cover = build_vector_engine_image_request_body("宣发首图", None, "720x540", 1, &[]);
+    let detail = build_vector_engine_image_request_body("详情单图", None, "720x1280", 1, &[]);
+    let poster = build_vector_engine_image_request_body("运营海报", None, "1280x720", 1, &[]);
+
+    assert_eq!(cover["size"], "720x540");
+    assert_eq!(detail["size"], "720x1280");
+    assert_eq!(poster["size"], "1280x720");
+}
+
+#[test]
+fn vector_engine_normalizes_2k_landscape_spec_size() {
+    let body = build_vector_engine_image_request_body("生成规范图", None, "2048x1152", 1, &[]);
+
+    assert_eq!(body["model"], GPT_IMAGE_2_MODEL);
+    assert_eq!(body["size"], "2048x1152");
+    assert_eq!(body["n"], 1);
+}
+
+#[test]
+fn vector_engine_request_body_can_use_nanobanana2_model() {
+    let body = build_vector_engine_image_request_body_with_model(
+        "gemini-3.1-flash-image-preview",
+        "生成图标 spritesheet",
+        None,
+        "512x512",
+        1,
+        &[],
+    );
+
+    assert_eq!(body["model"], "gemini-3.1-flash-image-preview");
+    assert_eq!(body["size"], "512x512");
+    assert_eq!(body["n"], 1);
+}
+
+#[test]
+fn vector_engine_request_body_can_use_nanobanana2_half_k() {
+    let body = build_vector_engine_image_request_body_with_model(
+        "gemini-3.1-flash-image-preview",
+        "生成图标 spritesheet",
+        None,
+        "512",
+        1,
+        &[],
+    );
+
+    assert_eq!(body["model"], "gemini-3.1-flash-image-preview");
+    assert_eq!(body["size"], "512");
+}
+
+#[test]
+fn nanobanana_generate_content_body_carries_aspect_ratio_and_image_size() {
+    let body = build_vector_engine_nanobanana_generate_content_request_body(
+        "生成角色图",
+        Some("文字、水印"),
+        "2:3",
+        "512",
+        &[],
+    );
+
+    assert_eq!(body["contents"][0]["role"], "user");
+    assert_eq!(
+        body["contents"][0]["parts"][0]["text"],
+        "生成角色图\n避免：文字、水印"
+    );
+    assert_eq!(body["generationConfig"]["responseModalities"][0], "IMAGE");
+    assert_eq!(
+        body["generationConfig"]["imageConfig"]["aspectRatio"],
+        "2:3"
+    );
+    assert_eq!(body["generationConfig"]["imageConfig"]["imageSize"], "512");
+    assert!(body.get("model").is_none());
+    assert!(body.get("n").is_none());
+}
+
+#[test]
+fn nanobanana_generate_content_url_uses_model_path() {
+    let settings = VectorEngineImageSettings {
+        base_url: "https://vector.example/v1".to_string(),
+        api_key: "test-key".to_string(),
+        request_timeout_ms: 1_000,
+    };
+
+    assert_eq!(
+        vector_engine_nanobanana_generate_content_url(&settings, "gemini-3.1-flash-image-preview"),
+        "https://vector.example/v1beta/models/gemini-3.1-flash-image-preview:generateContent"
+    );
+}
+
 #[tokio::test]
 async fn vector_engine_image_edit_retries_send_timeout_once_and_succeeds() {
     let listener = TcpListener::bind("127.0.0.1:0")
@@ -110,6 +203,73 @@ async fn vector_engine_image_edit_retries_send_timeout_once_and_succeeds() {
     server.abort();
 }
 
+#[tokio::test]
+async fn nanobanana_generate_content_posts_native_body_and_reads_inline_data() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("mock server should bind");
+    let server_addr = listener
+        .local_addr()
+        .expect("mock server address should be readable");
+    let server = tokio::spawn(async move {
+        let Ok((mut stream, _)) = listener.accept().await else {
+            return;
+        };
+        let mut request = Vec::new();
+        let mut buffer = [0_u8; 4096];
+        loop {
+            let Ok(read) = stream.read(&mut buffer).await else {
+                return;
+            };
+            if read == 0 {
+                return;
+            }
+            request.extend_from_slice(&buffer[..read]);
+            if request.windows(4).any(|window| window == b"\r\n\r\n") {
+                break;
+            }
+        }
+        let request_text = String::from_utf8_lossy(request.as_slice());
+        assert!(
+            request_text.contains("/v1beta/models/gemini-3.1-flash-image-preview:generateContent")
+        );
+        assert!(request_text.contains("\"aspectRatio\":\"2:3\""));
+        assert!(request_text.contains("\"imageSize\":\"512\""));
+
+        let body = r#"{"candidates":[{"content":{"parts":[{"inlineData":{"mimeType":"image/png","data":"iVBORw0KGgpyZXN0"}}]}}]}"#;
+        let response = format!(
+            "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        );
+        let _ = stream.write_all(response.as_bytes()).await;
+    });
+    let settings = VectorEngineImageSettings {
+        base_url: format!("http://{}", server_addr),
+        api_key: "test-key".to_string(),
+        request_timeout_ms: 1_000,
+    };
+    let client = build_vector_engine_image_http_client(&settings).expect("client should build");
+
+    let generated = create_vector_engine_nanobanana_generate_content(
+        &client,
+        &settings,
+        "gemini-3.1-flash-image-preview",
+        "生成角色图",
+        Some("文字、水印"),
+        "2:3",
+        "512",
+        &[],
+        "测试 nanobanana",
+    )
+    .await
+    .expect("nanobanana response should parse");
+
+    assert_eq!(generated.images.len(), 1);
+    assert_eq!(generated.images[0].mime_type, "image/png");
+    server.abort();
+}
+
 #[tokio::test]
 async fn vector_engine_image_generation_retries_upstream_502_once_and_succeeds() {
     let listener = TcpListener::bind("127.0.0.1:0")
diff --git a/server-rs/crates/shared-contracts/src/assets.rs b/server-rs/crates/shared-contracts/src/assets.rs
index e7c1e31bd..f140204c7 100644
--- a/server-rs/crates/shared-contracts/src/assets.rs
+++ b/server-rs/crates/shared-contracts/src/assets.rs
@@ -304,6 +304,175 @@ pub struct CharacterAnimationGenerateResponse {
     pub preview_video_path: Option<String>,
 }
 
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCharacterAnimationGenerateRequest {
+    pub source_layer_id: String,
+    pub source_image_src: String,
+    pub source_width: u32,
+    pub source_height: u32,
+    pub prompt_text: String,
+    pub resolution: String,
+    pub ratio: String,
+    pub frame_count: u32,
+    pub duration_seconds: u32,
+    pub price_mud_points: u32,
+    pub model: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCharacterAnimationFramePayload {
+    pub frame_index: u32,
+    pub image_src: String,
+    pub width: u32,
+    pub height: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorCharacterAnimationGenerateResponse {
+    pub ok: bool,
+    pub task_id: String,
+    pub model: String,
+    pub prompt: String,
+    pub preview_video_path: String,
+    pub frames: Vec<EditorCharacterAnimationFramePayload>,
+    pub frame_count: u32,
+    pub duration_seconds: u32,
+    pub frame_width: u32,
+    pub frame_height: u32,
+    pub fps: u32,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorVideoGenerateRequest {
+    pub prompt: String,
+    pub model: String,
+    pub aspect_ratio: String,
+    pub duration_seconds: u32,
+    pub resolution: String,
+    pub mode: String,
+    pub sound: String,
+    #[serde(default = "default_editor_video_web_search_enabled")]
+    pub web_search_enabled: bool,
+    pub price_mud_points: u32,
+    #[serde(default)]
+    pub reference_image_srcs: Vec<String>,
+    #[serde(default)]
+    pub reference_video_srcs: Vec<String>,
+    #[serde(default)]
+    pub reference_audio_srcs: Vec<String>,
+}
+
+fn default_editor_video_web_search_enabled() -> bool {
+    true
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorVideoGenerateResponse {
+    pub ok: bool,
+    pub video_src: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub asset_object_id: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub actual_prompt: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub task_id: String,
+    pub duration_seconds: u32,
+    pub resolution: String,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetGenerateRequest {
+    pub reference_image_src: String,
+    pub icon_descriptions: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub aspect_ratio: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image_size: Option<String>,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetIconPayload {
+    pub name: String,
+    pub image_src: String,
+    pub width: u32,
+    pub height: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorIconSpritesheetGenerateResponse {
+    pub spritesheet_image_src: String,
+    pub spritesheet_width: u32,
+    pub spritesheet_height: u32,
+    pub icon_image_srcs: Vec<EditorIconSpritesheetIconPayload>,
+    pub prompt: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub actual_prompt: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub task_id: String,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorSoundEffectGenerateRequest {
+    pub prompt: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    pub duration: u8,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorBackgroundMusicGenerateRequest {
+    pub gpt_description_prompt: String,
+    pub make_instrumental: bool,
+    pub price_mud_points: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct EditorAudioGenerateResponse {
+    pub ok: bool,
+    pub audio_src: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub object_key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub asset_object_id: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub actual_prompt: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub task_id: String,
+    pub price_mud_points: u32,
+    pub audio_kind: String,
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct CharacterAnimationDraftPayload {
@@ -815,6 +984,277 @@ mod tests {
         assert_eq!(payload["draftId"], json!("animation-import-1"));
     }
 
+    #[test]
+    fn editor_character_animation_request_uses_expected_camel_case_shape() {
+        let payload = serde_json::to_value(EditorCharacterAnimationGenerateRequest {
+            source_layer_id: "layer-1".to_string(),
+            source_image_src: "/generated-characters/hero/master.png".to_string(),
+            source_width: 768,
+            source_height: 1024,
+            prompt_text: "待机呼吸".to_string(),
+            resolution: "720p".to_string(),
+            ratio: "same".to_string(),
+            frame_count: 48,
+            duration_seconds: 6,
+            price_mud_points: 120,
+            model: "seedance2.0-fast".to_string(),
+        })
+        .expect("request should serialize");
+
+        assert_eq!(payload["sourceLayerId"], json!("layer-1"));
+        assert_eq!(
+            payload["sourceImageSrc"],
+            json!("/generated-characters/hero/master.png")
+        );
+        assert_eq!(payload["priceMudPoints"], json!(120));
+        assert_eq!(payload["model"], json!("seedance2.0-fast"));
+    }
+
+    #[test]
+    fn editor_character_animation_response_includes_frames_and_preview_video() {
+        let payload = serde_json::to_value(EditorCharacterAnimationGenerateResponse {
+            ok: true,
+            task_id: "task-1".to_string(),
+            model: "seedance2.0-fast".to_string(),
+            prompt: "生成游戏角色动画".to_string(),
+            preview_video_path: "/generated-character-drafts/editor/layer/preview.mp4".to_string(),
+            frames: vec![EditorCharacterAnimationFramePayload {
+                frame_index: 1,
+                image_src: "/generated-animations/editor/layer/frame01.png".to_string(),
+                width: 768,
+                height: 1024,
+            }],
+            frame_count: 1,
+            duration_seconds: 4,
+            frame_width: 768,
+            frame_height: 1024,
+            fps: 8,
+            price_mud_points: 40,
+        })
+        .expect("response should serialize");
+
+        assert_eq!(
+            payload["previewVideoPath"],
+            json!("/generated-character-drafts/editor/layer/preview.mp4")
+        );
+        assert_eq!(
+            payload["frames"][0]["imageSrc"],
+            json!("/generated-animations/editor/layer/frame01.png")
+        );
+        assert_eq!(payload["fps"], json!(8));
+    }
+
+    #[test]
+    fn editor_video_request_supports_lovart_model_contract() {
+        let payload = serde_json::to_value(EditorVideoGenerateRequest {
+            prompt: "让角色向镜头挥手".to_string(),
+            model: "kling3.0-omni".to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 5,
+            resolution: "480p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 100,
+            reference_image_srcs: Vec::new(),
+            reference_video_srcs: Vec::new(),
+            reference_audio_srcs: Vec::new(),
+        })
+        .expect("request should serialize");
+
+        assert_eq!(payload["aspectRatio"], json!("16:9"));
+        assert_eq!(payload["durationSeconds"], json!(5));
+        assert_eq!(payload["priceMudPoints"], json!(100));
+        assert_eq!(payload["model"], json!("kling3.0-omni"));
+        assert_eq!(payload["webSearchEnabled"], json!(true));
+    }
+
+    #[test]
+    fn editor_video_request_supports_seedance_multimodal_references() {
+        let payload = serde_json::to_value(EditorVideoGenerateRequest {
+            prompt: "参考素材生成视频".to_string(),
+            model: "seedance2.0-fast".to_string(),
+            aspect_ratio: "16:9".to_string(),
+            duration_seconds: 5,
+            resolution: "720p".to_string(),
+            mode: "std".to_string(),
+            sound: "off".to_string(),
+            web_search_enabled: true,
+            price_mud_points: 100,
+            reference_image_srcs: vec!["data:image/png;base64,image".to_string()],
+            reference_video_srcs: vec![
+                "generated-character-drafts/editor/seedance-references/video/demo.mp4".to_string(),
+            ],
+            reference_audio_srcs: vec!["data:audio/mpeg;base64,audio".to_string()],
+        })
+        .expect("request should serialize");
+
+        assert_eq!(
+            payload["referenceImageSrcs"],
+            json!(["data:image/png;base64,image"])
+        );
+        assert_eq!(
+            payload["referenceVideoSrcs"],
+            json!(["generated-character-drafts/editor/seedance-references/video/demo.mp4"])
+        );
+        assert_eq!(
+            payload["referenceAudioSrcs"],
+            json!(["data:audio/mpeg;base64,audio"])
+        );
+    }
+
+    #[test]
+    fn editor_video_response_uses_canvas_video_shape() {
+        let payload = serde_json::to_value(EditorVideoGenerateResponse {
+            ok: true,
+            video_src: "/generated-editor-videos/task-1/preview.mp4".to_string(),
+            object_key: Some("generated-character-drafts/editor-videos/task-1/preview.mp4".to_string()),
+            asset_object_id: Some("assetobj_video_1".to_string()),
+            width: 1280,
+            height: 720,
+            source_type: "generated".to_string(),
+            prompt: "让角色向镜头挥手".to_string(),
+            actual_prompt: Some("让角色向镜头挥手".to_string()),
+            model: "kling3.0-omni".to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: "task-1".to_string(),
+            duration_seconds: 5,
+            resolution: "480p".to_string(),
+            price_mud_points: 100,
+        })
+        .expect("response should serialize");
+
+        assert_eq!(
+            payload["videoSrc"],
+            json!("/generated-editor-videos/task-1/preview.mp4")
+        );
+        assert_eq!(
+            payload["objectKey"],
+            json!("generated-character-drafts/editor-videos/task-1/preview.mp4")
+        );
+        assert_eq!(payload["assetObjectId"], json!("assetobj_video_1"));
+        assert_eq!(payload["sourceType"], json!("generated"));
+        assert_eq!(payload["durationSeconds"], json!(5));
+    }
+
+    #[test]
+    fn editor_icon_spritesheet_request_and_response_include_price() {
+        let request_payload = serde_json::to_value(EditorIconSpritesheetGenerateRequest {
+            reference_image_src: "data:image/png;base64,spec".to_string(),
+            icon_descriptions: vec!["返回按钮".to_string(), "设置按钮".to_string()],
+            model: Some("gemini-3.1-flash-image-preview".to_string()),
+            aspect_ratio: Some("1:1".to_string()),
+            image_size: Some("1K".to_string()),
+            price_mud_points: 12,
+        })
+        .expect("request should serialize");
+
+        assert_eq!(
+            request_payload["referenceImageSrc"],
+            json!("data:image/png;base64,spec")
+        );
+        assert_eq!(request_payload["priceMudPoints"], json!(12));
+
+        let response_payload = serde_json::to_value(EditorIconSpritesheetGenerateResponse {
+            spritesheet_image_src: "data:image/png;base64,sheet".to_string(),
+            spritesheet_width: 512,
+            spritesheet_height: 512,
+            icon_image_srcs: vec![EditorIconSpritesheetIconPayload {
+                name: "返回按钮".to_string(),
+                image_src: "data:image/png;base64,back".to_string(),
+                width: 128,
+                height: 128,
+            }],
+            prompt: "图标 prompt".to_string(),
+            actual_prompt: Some("图标 prompt".to_string()),
+            model: "gemini-3.1-flash-image-preview".to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: "task-icons".to_string(),
+            price_mud_points: 12,
+        })
+        .expect("response should serialize");
+
+        assert_eq!(response_payload["priceMudPoints"], json!(12));
+        assert_eq!(
+            response_payload["iconImageSrcs"][0]["name"],
+            json!("返回按钮")
+        );
+    }
+
+    #[test]
+    fn editor_audio_requests_and_response_use_canvas_audio_shape() {
+        let sound_payload = serde_json::to_value(EditorSoundEffectGenerateRequest {
+            prompt: "金币掉落叮当声".to_string(),
+            model: Some("audio1.0".to_string()),
+            duration: 7,
+            price_mud_points: 10,
+        })
+        .expect("sound request should serialize");
+        assert_eq!(sound_payload["prompt"], json!("金币掉落叮当声"));
+        assert_eq!(sound_payload["model"], json!("audio1.0"));
+        assert_eq!(sound_payload["duration"], json!(7));
+        assert_eq!(sound_payload["priceMudPoints"], json!(10));
+        assert!(sound_payload.get("sound").is_none());
+        assert!(sound_payload.get("type").is_none());
+        assert!(sound_payload.get("tempo").is_none());
+
+        let parsed_sound_payload: EditorSoundEffectGenerateRequest =
+            serde_json::from_value(sound_payload)
+                .expect("sound request with duration should deserialize");
+        assert_eq!(parsed_sound_payload.prompt, "金币掉落叮当声");
+        assert_eq!(parsed_sound_payload.duration, 7);
+
+        let unset_model_payload = serde_json::to_value(EditorSoundEffectGenerateRequest {
+            prompt: "按钮确认短促音".to_string(),
+            model: None,
+            duration: 5,
+            price_mud_points: 10,
+        })
+        .expect("sound request with unset model should serialize");
+        assert!(unset_model_payload.get("model").is_none());
+        assert_eq!(unset_model_payload["duration"], json!(5));
+
+        let music_payload = serde_json::to_value(EditorBackgroundMusicGenerateRequest {
+            gpt_description_prompt: "森林冒险背景音乐".to_string(),
+            make_instrumental: true,
+            price_mud_points: 5,
+        })
+        .expect("background music request should serialize");
+        assert_eq!(
+            music_payload["gptDescriptionPrompt"],
+            json!("森林冒险背景音乐")
+        );
+        assert_eq!(music_payload["makeInstrumental"], json!(true));
+
+        let response_payload = serde_json::to_value(EditorAudioGenerateResponse {
+            ok: true,
+            audio_src: "/generated-character-drafts/editor-audios/sfx.mp3".to_string(),
+            object_key: Some("generated-character-drafts/editor-audios/sfx.mp3".to_string()),
+            asset_object_id: Some("assetobj_audio_1".to_string()),
+            width: 420,
+            height: 120,
+            source_type: "generated".to_string(),
+            prompt: "金币掉落叮当声".to_string(),
+            actual_prompt: Some("金币掉落叮当声".to_string()),
+            model: "audio1.0".to_string(),
+            provider: "VectorEngine".to_string(),
+            task_id: "sound-task-1".to_string(),
+            price_mud_points: 10,
+            audio_kind: "sound-effect".to_string(),
+        })
+        .expect("audio response should serialize");
+        assert_eq!(
+            response_payload["audioSrc"],
+            json!("/generated-character-drafts/editor-audios/sfx.mp3")
+        );
+        assert_eq!(
+            response_payload["objectKey"],
+            json!("generated-character-drafts/editor-audios/sfx.mp3")
+        );
+        assert_eq!(response_payload["assetObjectId"], json!("assetobj_audio_1"));
+        assert_eq!(response_payload["audioKind"], json!("sound-effect"));
+    }
+
     #[test]
     fn character_workflow_cache_response_keeps_legacy_shape() {
         let payload = serde_json::to_value(CharacterWorkflowCacheSaveResponse {
diff --git a/server-rs/crates/shared-contracts/src/creation_audio.rs b/server-rs/crates/shared-contracts/src/creation_audio.rs
index f6a3ca419..ff353c6b7 100644
--- a/server-rs/crates/shared-contracts/src/creation_audio.rs
+++ b/server-rs/crates/shared-contracts/src/creation_audio.rs
@@ -88,6 +88,8 @@ pub struct GeneratedAudioAssetResponse {
     #[serde(default)]
     pub asset_object_id: Option<String>,
     #[serde(default)]
+    pub object_key: Option<String>,
+    #[serde(default)]
     pub asset_kind: Option<String>,
     #[serde(default)]
     pub audio_src: Option<String>,
diff --git a/server-rs/crates/spacetime-client/src/editor_project.rs b/server-rs/crates/spacetime-client/src/editor_project.rs
new file mode 100644
index 000000000..89c009289
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/editor_project.rs
@@ -0,0 +1,359 @@
+use super::*;
+
+impl SpacetimeClient {
+    pub async fn create_editor_project(
+        &self,
+        input: EditorProjectCreateRecordInput,
+    ) -> Result<EditorProjectRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "create_editor_project_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_editor_project_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_project_required_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn get_recent_editor_project(
+        &self,
+        owner_user_id: String,
+    ) -> Result<Option<EditorProjectRecord>, SpacetimeClientError> {
+        let procedure_input = EditorProjectGetRecentInput { owner_user_id };
+
+        self.call_after_connect(
+            "get_recent_editor_project_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_recent_editor_project_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_project_optional_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn get_editor_project(
+        &self,
+        input: EditorProjectGetRecordInput,
+    ) -> Result<EditorProjectRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "get_editor_project_and_return",
+            move |connection, sender| {
+                connection.procedures().get_editor_project_and_return_then(
+                    procedure_input,
+                    move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_project_required_procedure_result);
+                        send_once(&sender, mapped);
+                    },
+                );
+            },
+        )
+        .await
+    }
+
+    pub async fn list_editor_projects(
+        &self,
+        owner_user_id: String,
+    ) -> Result<Vec<EditorProjectRecord>, SpacetimeClientError> {
+        let procedure_input = EditorProjectListInput { owner_user_id };
+
+        self.call_after_connect(
+            "list_editor_projects_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .list_editor_projects_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_project_list_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn rename_editor_project(
+        &self,
+        input: EditorProjectRenameRecordInput,
+    ) -> Result<EditorProjectRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "rename_editor_project_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .rename_editor_project_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_project_required_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn delete_editor_project(
+        &self,
+        input: EditorProjectDeleteRecordInput,
+    ) -> Result<String, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "delete_editor_project_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .delete_editor_project_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_project_delete_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn save_editor_project_layout(
+        &self,
+        input: EditorProjectLayoutSaveRecordInput,
+    ) -> Result<EditorProjectRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "save_editor_project_layout_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .save_editor_project_layout_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_project_required_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn create_editor_project_resource(
+        &self,
+        input: EditorProjectResourceCreateRecordInput,
+    ) -> Result<EditorProjectResourceRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "create_editor_project_resource_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_editor_project_resource_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_project_resource_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn get_editor_asset_library(
+        &self,
+        owner_user_id: String,
+        now_micros: i64,
+    ) -> Result<EditorAssetLibraryRecord, SpacetimeClientError> {
+        let procedure_input = EditorAssetLibraryGetInput {
+            owner_user_id,
+            now_micros,
+        };
+
+        self.call_after_connect(
+            "get_editor_asset_library_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .get_editor_asset_library_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_asset_library_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn create_editor_asset_folder(
+        &self,
+        input: EditorAssetFolderCreateRecordInput,
+    ) -> Result<EditorAssetFolderRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "create_editor_asset_folder_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_editor_asset_folder_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_asset_folder_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn update_editor_asset_folder(
+        &self,
+        input: EditorAssetFolderUpdateRecordInput,
+    ) -> Result<EditorAssetFolderRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "update_editor_asset_folder_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .update_editor_asset_folder_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_asset_folder_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn delete_editor_asset_folder(
+        &self,
+        input: EditorAssetFolderDeleteRecordInput,
+    ) -> Result<EditorAssetLibraryRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "delete_editor_asset_folder_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .delete_editor_asset_folder_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_editor_asset_folder_library_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+
+    pub async fn create_editor_asset(
+        &self,
+        input: EditorAssetCreateRecordInput,
+    ) -> Result<EditorAssetRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "create_editor_asset_and_return",
+            move |connection, sender| {
+                connection.procedures().create_editor_asset_and_return_then(
+                    procedure_input,
+                    move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_asset_procedure_result);
+                        send_once(&sender, mapped);
+                    },
+                );
+            },
+        )
+        .await
+    }
+
+    pub async fn update_editor_asset(
+        &self,
+        input: EditorAssetUpdateRecordInput,
+    ) -> Result<EditorAssetRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "update_editor_asset_and_return",
+            move |connection, sender| {
+                connection.procedures().update_editor_asset_and_return_then(
+                    procedure_input,
+                    move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_asset_procedure_result);
+                        send_once(&sender, mapped);
+                    },
+                );
+            },
+        )
+        .await
+    }
+
+    pub async fn delete_editor_asset(
+        &self,
+        input: EditorAssetDeleteRecordInput,
+    ) -> Result<EditorAssetRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "delete_editor_asset_and_return",
+            move |connection, sender| {
+                connection.procedures().delete_editor_asset_and_return_then(
+                    procedure_input,
+                    move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_editor_asset_procedure_result);
+                        send_once(&sender, mapped);
+                    },
+                );
+            },
+        )
+        .await
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/external_api_key.rs b/server-rs/crates/spacetime-client/src/external_api_key.rs
new file mode 100644
index 000000000..3524f12c0
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/external_api_key.rs
@@ -0,0 +1,94 @@
+use super::*;
+
+impl SpacetimeClient {
+    pub async fn create_external_api_key(
+        &self,
+        input: ExternalApiKeyCreateRecordInput,
+    ) -> Result<ExternalApiKeyRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "create_external_api_key_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .create_external_api_key_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_external_api_key_single_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn list_external_api_keys(
+        &self,
+        owner_user_id: String,
+    ) -> Result<Vec<ExternalApiKeyRecord>, SpacetimeClientError> {
+        let procedure_input = ExternalApiKeyListInput { owner_user_id };
+
+        self.call_after_connect(
+            "list_external_api_keys_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .list_external_api_keys_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_external_api_key_list_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn revoke_external_api_key(
+        &self,
+        input: ExternalApiKeyRevokeRecordInput,
+    ) -> Result<ExternalApiKeyRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "revoke_external_api_key_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .revoke_external_api_key_and_return_then(procedure_input, move |_, result| {
+                        let mapped = result
+                            .map_err(SpacetimeClientError::from_sdk_error)
+                            .and_then(map_external_api_key_single_procedure_result);
+                        send_once(&sender, mapped);
+                    });
+            },
+        )
+        .await
+    }
+
+    pub async fn authenticate_external_api_key(
+        &self,
+        input: ExternalApiKeyAuthenticateRecordInput,
+    ) -> Result<ExternalApiKeyRecord, SpacetimeClientError> {
+        let procedure_input = input.into();
+
+        self.call_after_connect(
+            "authenticate_external_api_key_and_return",
+            move |connection, sender| {
+                connection
+                    .procedures()
+                    .authenticate_external_api_key_and_return_then(
+                        procedure_input,
+                        move |_, result| {
+                            let mapped = result
+                                .map_err(SpacetimeClientError::from_sdk_error)
+                                .and_then(map_external_api_key_single_procedure_result);
+                            send_once(&sender, mapped);
+                        },
+                    );
+            },
+        )
+        .await
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/lib.rs b/server-rs/crates/spacetime-client/src/lib.rs
index 4cf5cf16f..08d1f0371 100644
--- a/server-rs/crates/spacetime-client/src/lib.rs
+++ b/server-rs/crates/spacetime-client/src/lib.rs
@@ -30,16 +30,25 @@ pub use mapper::{
     CustomWorldPublishGateRecord, CustomWorldPublishWorldRecord,
     CustomWorldPublishWorldRecordInput, CustomWorldPublishedProfileCompileRecord,
     CustomWorldResultPreviewBlockerRecord, CustomWorldSupportedActionRecord,
-    CustomWorldWorkSummaryRecord, ExternalGenerationJobClaimRecordInput,
-    ExternalGenerationJobCompleteRecordInput, ExternalGenerationJobEnqueueRecordInput,
-    ExternalGenerationJobFailRecordInput, ExternalGenerationJobGetRecordInput,
-    ExternalGenerationJobRecord, ExternalGenerationJobRenewLeaseRecordInput,
-    ExternalGenerationQueueStatsRecord, JumpHopActionRequest, JumpHopActionResponse,
-    JumpHopActionType, JumpHopCharacterAsset, JumpHopDifficulty, JumpHopDraftResponse,
-    JumpHopGalleryCardResponse, JumpHopGalleryDetailResponse, JumpHopGalleryResponse,
-    JumpHopGenerationStatus, JumpHopJumpRequest, JumpHopJumpResponse, JumpHopJumpResult,
-    JumpHopLastJump, JumpHopPath, JumpHopPlatform, JumpHopRestartRunRequest, JumpHopRunResponse,
-    JumpHopRunStatus, JumpHopRuntimeRunSnapshotResponse, JumpHopScoring, JumpHopSessionResponse,
+    CustomWorldWorkSummaryRecord, EditorAssetCreateRecordInput, EditorAssetDeleteRecordInput,
+    EditorAssetFolderCreateRecordInput, EditorAssetFolderDeleteRecordInput,
+    EditorAssetFolderRecord, EditorAssetFolderUpdateRecordInput, EditorAssetLibraryRecord,
+    EditorAssetRecord, EditorAssetUpdateRecordInput, EditorCanvasRecord,
+    EditorCanvasViewportRecord, EditorProjectCreateRecordInput, EditorProjectDeleteRecordInput,
+    EditorProjectGetRecordInput, EditorProjectLayoutSaveRecordInput, EditorProjectRecord,
+    EditorProjectRenameRecordInput, EditorProjectResourceCreateRecordInput,
+    EditorProjectResourceRecord, ExternalApiKeyAuthenticateRecordInput,
+    ExternalApiKeyCreateRecordInput, ExternalApiKeyRecord, ExternalApiKeyRevokeRecordInput,
+    ExternalGenerationJobClaimRecordInput, ExternalGenerationJobCompleteRecordInput,
+    ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobFailRecordInput,
+    ExternalGenerationJobGetRecordInput, ExternalGenerationJobRecord,
+    ExternalGenerationJobRenewLeaseRecordInput, ExternalGenerationQueueStatsRecord,
+    JumpHopActionRequest, JumpHopActionResponse, JumpHopActionType, JumpHopCharacterAsset,
+    JumpHopDifficulty, JumpHopDraftResponse, JumpHopGalleryCardResponse,
+    JumpHopGalleryDetailResponse, JumpHopGalleryResponse, JumpHopGenerationStatus,
+    JumpHopJumpRequest, JumpHopJumpResponse, JumpHopJumpResult, JumpHopLastJump, JumpHopPath,
+    JumpHopPlatform, JumpHopRestartRunRequest, JumpHopRunResponse, JumpHopRunStatus,
+    JumpHopRuntimeRunSnapshotResponse, JumpHopScoring, JumpHopSessionResponse,
     JumpHopSessionSnapshotResponse, JumpHopStartRunRequest, JumpHopStylePreset, JumpHopTileAsset,
     JumpHopTileType, JumpHopWorkDetailResponse, JumpHopWorkMutationResponse,
     JumpHopWorkProfileResponse, JumpHopWorkSummaryResponse, JumpHopWorksResponse,
@@ -117,7 +126,10 @@ pub use bark_battle::{
 pub mod big_fish;
 pub mod combat;
 pub mod custom_world;
+pub mod editor_project;
+pub mod external_api_key;
 pub mod external_generation;
+
 pub mod inventory;
 pub mod jump_hop;
 pub mod match3d;
diff --git a/server-rs/crates/spacetime-client/src/mapper.rs b/server-rs/crates/spacetime-client/src/mapper.rs
index 1e6fae4f2..e2dc114d0 100644
--- a/server-rs/crates/spacetime-client/src/mapper.rs
+++ b/server-rs/crates/spacetime-client/src/mapper.rs
@@ -8,7 +8,10 @@ mod big_fish;
 mod combat;
 mod common;
 mod custom_world;
+mod editor_project;
+mod external_api_key;
 mod external_generation;
+
 mod inventory;
 mod jump_hop;
 mod match3d;
@@ -69,6 +72,19 @@ pub use self::common::{
     VisualNovelRunSnapshotRecordInput, VisualNovelRunStartRecordInput,
     VisualNovelWorkCompileRecordInput,
 };
+pub use self::editor_project::{
+    EditorAssetCreateRecordInput, EditorAssetDeleteRecordInput, EditorAssetFolderCreateRecordInput,
+    EditorAssetFolderDeleteRecordInput, EditorAssetFolderRecord,
+    EditorAssetFolderUpdateRecordInput, EditorAssetLibraryRecord, EditorAssetRecord,
+    EditorAssetUpdateRecordInput, EditorCanvasRecord, EditorCanvasViewportRecord,
+    EditorProjectCreateRecordInput, EditorProjectDeleteRecordInput, EditorProjectGetRecordInput,
+    EditorProjectLayoutSaveRecordInput, EditorProjectRecord, EditorProjectRenameRecordInput,
+    EditorProjectResourceCreateRecordInput, EditorProjectResourceRecord,
+};
+pub use self::external_api_key::{
+    ExternalApiKeyAuthenticateRecordInput, ExternalApiKeyCreateRecordInput, ExternalApiKeyRecord,
+    ExternalApiKeyRevokeRecordInput,
+};
 pub use self::external_generation::{
     ExternalGenerationJobClaimRecordInput, ExternalGenerationJobCompleteRecordInput,
     ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobFailRecordInput,
@@ -185,6 +201,16 @@ pub(crate) use self::custom_world::{
     parse_rpg_agent_operation_status_record, parse_rpg_agent_operation_type_record,
     parse_rpg_agent_stage_record,
 };
+pub(crate) use self::editor_project::{
+    map_editor_asset_folder_library_procedure_result, map_editor_asset_folder_procedure_result,
+    map_editor_asset_library_procedure_result, map_editor_asset_procedure_result,
+    map_editor_project_delete_procedure_result, map_editor_project_list_procedure_result,
+    map_editor_project_optional_procedure_result, map_editor_project_required_procedure_result,
+    map_editor_project_resource_procedure_result,
+};
+pub(crate) use self::external_api_key::{
+    map_external_api_key_list_procedure_result, map_external_api_key_single_procedure_result,
+};
 pub(crate) use self::external_generation::{
     map_external_generation_job_claim_result, map_external_generation_job_procedure_result,
     map_external_generation_queue_stats_result,
diff --git a/server-rs/crates/spacetime-client/src/mapper/editor_project.rs b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
new file mode 100644
index 000000000..b53925b53
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/mapper/editor_project.rs
@@ -0,0 +1,640 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct EditorCanvasViewportRecord {
+    pub x: f64,
+    pub y: f64,
+    pub scale: f64,
+}
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct EditorProjectRecord {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub canvas: EditorCanvasRecord,
+    pub viewport: EditorCanvasViewportRecord,
+    pub layers: serde_json::Value,
+    pub resources: Vec<EditorProjectResourceRecord>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct EditorCanvasRecord {
+    pub canvas_id: String,
+    pub project_id: String,
+    pub title: String,
+    pub viewport: EditorCanvasViewportRecord,
+    pub layers: serde_json::Value,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct EditorProjectResourceRecord {
+    pub resource_id: String,
+    pub project_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs: Option<serde_json::Value>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct EditorAssetFolderRecord {
+    pub folder_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub collapsed: bool,
+    pub system_default: bool,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct EditorAssetRecord {
+    pub asset_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs: Option<serde_json::Value>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct EditorAssetLibraryRecord {
+    pub folders: Vec<EditorAssetFolderRecord>,
+    pub assets: Vec<EditorAssetRecord>,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct EditorProjectCreateRecordInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorProjectGetRecordInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorProjectRenameRecordInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorProjectDeleteRecordInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct EditorProjectLayoutSaveRecordInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub viewport: EditorCanvasViewportRecord,
+    pub layers_json: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorProjectResourceCreateRecordInput {
+    pub resource_id: String,
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetFolderCreateRecordInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetFolderUpdateRecordInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub collapsed: Option<bool>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetFolderDeleteRecordInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetCreateRecordInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetUpdateRecordInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub folder_id: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EditorAssetDeleteRecordInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+}
+
+impl From<EditorProjectCreateRecordInput> for crate::module_bindings::EditorProjectCreateInput {
+    fn from(input: EditorProjectCreateRecordInput) -> Self {
+        Self {
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+            title: input.title,
+            now_micros: input.now_micros,
+        }
+    }
+}
+
+impl From<EditorProjectGetRecordInput> for crate::module_bindings::EditorProjectGetInput {
+    fn from(input: EditorProjectGetRecordInput) -> Self {
+        Self {
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+        }
+    }
+}
+
+impl From<EditorProjectRenameRecordInput> for crate::module_bindings::EditorProjectRenameInput {
+    fn from(input: EditorProjectRenameRecordInput) -> Self {
+        Self {
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+            title: input.title,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorProjectDeleteRecordInput> for crate::module_bindings::EditorProjectDeleteInput {
+    fn from(input: EditorProjectDeleteRecordInput) -> Self {
+        Self {
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+        }
+    }
+}
+
+impl From<EditorProjectLayoutSaveRecordInput>
+    for crate::module_bindings::EditorProjectLayoutSaveInput
+{
+    fn from(input: EditorProjectLayoutSaveRecordInput) -> Self {
+        Self {
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+            viewport: crate::module_bindings::EditorProjectViewportSnapshot {
+                x: input.viewport.x,
+                y: input.viewport.y,
+                scale: input.viewport.scale,
+            },
+            layers_json: input.layers_json,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorProjectResourceCreateRecordInput>
+    for crate::module_bindings::EditorProjectResourceCreateInput
+{
+    fn from(input: EditorProjectResourceCreateRecordInput) -> Self {
+        Self {
+            resource_id: input.resource_id,
+            project_id: input.project_id,
+            owner_user_id: input.owner_user_id,
+            asset_object_id: input.asset_object_id,
+            image_src: input.image_src,
+            object_key: input.object_key,
+            width: input.width,
+            height: input.height,
+            source_type: input.source_type,
+            prompt: input.prompt,
+            actual_prompt: input.actual_prompt,
+            model: input.model,
+            provider: input.provider,
+            task_id: input.task_id,
+            source_resource_id: input.source_resource_id,
+            asset_kind: input.asset_kind,
+            generation_inputs_json: input.generation_inputs_json,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorAssetFolderCreateRecordInput>
+    for crate::module_bindings::EditorAssetFolderCreateInput
+{
+    fn from(input: EditorAssetFolderCreateRecordInput) -> Self {
+        Self {
+            folder_id: input.folder_id,
+            owner_user_id: input.owner_user_id,
+            label: input.label,
+            sort_order: input.sort_order,
+            now_micros: input.now_micros,
+        }
+    }
+}
+
+impl From<EditorAssetFolderUpdateRecordInput>
+    for crate::module_bindings::EditorAssetFolderUpdateInput
+{
+    fn from(input: EditorAssetFolderUpdateRecordInput) -> Self {
+        Self {
+            folder_id: input.folder_id,
+            owner_user_id: input.owner_user_id,
+            label: input.label,
+            collapsed: input.collapsed,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorAssetFolderDeleteRecordInput>
+    for crate::module_bindings::EditorAssetFolderDeleteInput
+{
+    fn from(input: EditorAssetFolderDeleteRecordInput) -> Self {
+        Self {
+            folder_id: input.folder_id,
+            owner_user_id: input.owner_user_id,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorAssetCreateRecordInput> for crate::module_bindings::EditorAssetCreateInput {
+    fn from(input: EditorAssetCreateRecordInput) -> Self {
+        Self {
+            asset_id: input.asset_id,
+            owner_user_id: input.owner_user_id,
+            folder_id: input.folder_id,
+            label: input.label,
+            asset_object_id: input.asset_object_id,
+            image_src: input.image_src,
+            object_key: input.object_key,
+            width: input.width,
+            height: input.height,
+            source_type: input.source_type,
+            prompt: input.prompt,
+            actual_prompt: input.actual_prompt,
+            model: input.model,
+            provider: input.provider,
+            task_id: input.task_id,
+            asset_kind: input.asset_kind,
+            generation_inputs_json: input.generation_inputs_json,
+            now_micros: input.now_micros,
+        }
+    }
+}
+
+impl From<EditorAssetUpdateRecordInput> for crate::module_bindings::EditorAssetUpdateInput {
+    fn from(input: EditorAssetUpdateRecordInput) -> Self {
+        Self {
+            asset_id: input.asset_id,
+            owner_user_id: input.owner_user_id,
+            label: input.label,
+            folder_id: input.folder_id,
+            updated_at_micros: input.updated_at_micros,
+        }
+    }
+}
+
+impl From<EditorAssetDeleteRecordInput> for crate::module_bindings::EditorAssetDeleteInput {
+    fn from(input: EditorAssetDeleteRecordInput) -> Self {
+        Self {
+            asset_id: input.asset_id,
+            owner_user_id: input.owner_user_id,
+        }
+    }
+}
+
+pub(crate) fn map_editor_project_optional_procedure_result(
+    result: EditorProjectProcedureResult,
+) -> Result<Option<EditorProjectRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result.project.map(map_editor_project_snapshot).transpose()
+}
+
+pub(crate) fn map_editor_project_required_procedure_result(
+    result: EditorProjectProcedureResult,
+) -> Result<EditorProjectRecord, SpacetimeClientError> {
+    map_editor_project_optional_procedure_result(result)?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布工程快照"))
+}
+
+pub(crate) fn map_editor_project_list_procedure_result(
+    result: EditorProjectListProcedureResult,
+) -> Result<Vec<EditorProjectRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .projects
+        .into_iter()
+        .map(map_editor_project_snapshot)
+        .collect()
+}
+
+pub(crate) fn map_editor_project_delete_procedure_result(
+    result: EditorProjectDeleteProcedureResult,
+) -> Result<String, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .deleted_project_id
+        .filter(|project_id| !project_id.trim().is_empty())
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布工程删除结果"))
+}
+
+pub(crate) fn map_editor_project_resource_procedure_result(
+    result: EditorProjectResourceProcedureResult,
+) -> Result<EditorProjectResourceRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .resource
+        .map(map_editor_project_resource_snapshot)
+        .transpose()?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布资源快照"))
+}
+
+pub(crate) fn map_editor_asset_library_procedure_result(
+    result: EditorAssetLibraryProcedureResult,
+) -> Result<EditorAssetLibraryRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .library
+        .map(map_editor_asset_library_snapshot)
+        .transpose()?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布素材库快照"))
+}
+
+pub(crate) fn map_editor_asset_folder_procedure_result(
+    result: EditorAssetFolderProcedureResult,
+) -> Result<EditorAssetFolderRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .folder
+        .map(map_editor_asset_folder_snapshot)
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布素材文件夹快照"))
+}
+
+pub(crate) fn map_editor_asset_folder_library_procedure_result(
+    result: EditorAssetFolderProcedureResult,
+) -> Result<EditorAssetLibraryRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .library
+        .map(map_editor_asset_library_snapshot)
+        .transpose()?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布素材库快照"))
+}
+
+pub(crate) fn map_editor_asset_procedure_result(
+    result: EditorAssetProcedureResult,
+) -> Result<EditorAssetRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .asset
+        .map(map_editor_asset_snapshot)
+        .transpose()?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("图片画布素材快照"))
+}
+
+fn map_editor_project_snapshot(
+    snapshot: EditorProjectSnapshot,
+) -> Result<EditorProjectRecord, SpacetimeClientError> {
+    let layers: serde_json::Value =
+        serde_json::from_str(&snapshot.canvas.layers_json).map_err(|error| {
+            SpacetimeClientError::validation_failed(format!(
+                "图片画布图层布局 JSON 无法解析：{error}"
+            ))
+        })?;
+    let viewport = EditorCanvasViewportRecord {
+        x: snapshot.canvas.viewport.x,
+        y: snapshot.canvas.viewport.y,
+        scale: snapshot.canvas.viewport.scale,
+    };
+    let canvas = EditorCanvasRecord {
+        canvas_id: snapshot.canvas.canvas_id,
+        project_id: snapshot.canvas.project_id,
+        title: snapshot.canvas.title,
+        viewport: viewport.clone(),
+        layers: layers.clone(),
+        created_at: format_timestamp_micros(snapshot.canvas.created_at_micros),
+        updated_at: format_timestamp_micros(snapshot.canvas.updated_at_micros),
+    };
+
+    Ok(EditorProjectRecord {
+        project_id: snapshot.project_id,
+        owner_user_id: snapshot.owner_user_id,
+        title: snapshot.title,
+        canvas,
+        viewport,
+        layers,
+        resources: snapshot
+            .resources
+            .into_iter()
+            .map(map_editor_project_resource_snapshot)
+            .collect::<Result<Vec<_>, _>>()?,
+        created_at: format_timestamp_micros(snapshot.created_at_micros),
+        updated_at: format_timestamp_micros(snapshot.updated_at_micros),
+    })
+}
+
+fn map_editor_project_resource_snapshot(
+    snapshot: EditorProjectResourceSnapshot,
+) -> Result<EditorProjectResourceRecord, SpacetimeClientError> {
+    let generation_inputs = parse_optional_generation_inputs_json(
+        snapshot.generation_inputs_json.as_deref(),
+        "图片画布资源生成输入 JSON",
+    )?;
+    Ok(EditorProjectResourceRecord {
+        resource_id: snapshot.resource_id,
+        project_id: snapshot.project_id,
+        asset_object_id: snapshot.asset_object_id,
+        image_src: snapshot.image_src,
+        object_key: snapshot.object_key,
+        width: snapshot.width,
+        height: snapshot.height,
+        source_type: snapshot.source_type,
+        prompt: snapshot.prompt,
+        actual_prompt: snapshot.actual_prompt,
+        model: snapshot.model,
+        provider: snapshot.provider,
+        task_id: snapshot.task_id,
+        source_resource_id: snapshot.source_resource_id,
+        asset_kind: snapshot.asset_kind,
+        generation_inputs,
+        created_at: format_timestamp_micros(snapshot.created_at_micros),
+        updated_at: format_timestamp_micros(snapshot.updated_at_micros),
+    })
+}
+
+fn map_editor_asset_library_snapshot(
+    snapshot: EditorAssetLibrarySnapshot,
+) -> Result<EditorAssetLibraryRecord, SpacetimeClientError> {
+    Ok(EditorAssetLibraryRecord {
+        folders: snapshot
+            .folders
+            .into_iter()
+            .map(map_editor_asset_folder_snapshot)
+            .collect(),
+        assets: snapshot
+            .assets
+            .into_iter()
+            .map(map_editor_asset_snapshot)
+            .collect::<Result<Vec<_>, _>>()?,
+    })
+}
+
+fn map_editor_asset_folder_snapshot(
+    snapshot: EditorAssetFolderSnapshot,
+) -> EditorAssetFolderRecord {
+    EditorAssetFolderRecord {
+        folder_id: snapshot.folder_id,
+        label: snapshot.label,
+        sort_order: snapshot.sort_order,
+        collapsed: snapshot.collapsed,
+        system_default: snapshot.system_default,
+        created_at: format_timestamp_micros(snapshot.created_at_micros),
+        updated_at: format_timestamp_micros(snapshot.updated_at_micros),
+    }
+}
+
+fn map_editor_asset_snapshot(
+    snapshot: EditorAssetSnapshot,
+) -> Result<EditorAssetRecord, SpacetimeClientError> {
+    let generation_inputs = parse_optional_generation_inputs_json(
+        snapshot.generation_inputs_json.as_deref(),
+        "图片画布素材生成输入 JSON",
+    )?;
+    Ok(EditorAssetRecord {
+        asset_id: snapshot.asset_id,
+        folder_id: snapshot.folder_id,
+        label: snapshot.label,
+        asset_object_id: snapshot.asset_object_id,
+        image_src: snapshot.image_src,
+        object_key: snapshot.object_key,
+        width: snapshot.width,
+        height: snapshot.height,
+        source_type: snapshot.source_type,
+        prompt: snapshot.prompt,
+        actual_prompt: snapshot.actual_prompt,
+        model: snapshot.model,
+        provider: snapshot.provider,
+        task_id: snapshot.task_id,
+        asset_kind: snapshot.asset_kind,
+        generation_inputs,
+        created_at: format_timestamp_micros(snapshot.created_at_micros),
+        updated_at: format_timestamp_micros(snapshot.updated_at_micros),
+    })
+}
+
+fn parse_optional_generation_inputs_json(
+    raw_json: Option<&str>,
+    label: &str,
+) -> Result<Option<serde_json::Value>, SpacetimeClientError> {
+    let Some(raw_json) = raw_json.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(None);
+    };
+    serde_json::from_str(raw_json).map(Some).map_err(|error| {
+        SpacetimeClientError::validation_failed(format!("{label} 无法解析：{error}"))
+    })
+}
diff --git a/server-rs/crates/spacetime-client/src/mapper/external_api_key.rs b/server-rs/crates/spacetime-client/src/mapper/external_api_key.rs
new file mode 100644
index 000000000..1092c1f50
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/mapper/external_api_key.rs
@@ -0,0 +1,118 @@
+use super::*;
+
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct ExternalApiKeyRecord {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub scopes: Vec<String>,
+    pub created_at: String,
+    pub last_used_at: Option<String>,
+    pub revoked_at: Option<String>,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ExternalApiKeyCreateRecordInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub key_hash: String,
+    pub scopes: Vec<String>,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ExternalApiKeyRevokeRecordInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub revoked_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ExternalApiKeyAuthenticateRecordInput {
+    pub key_hash: String,
+    pub used_at_micros: i64,
+}
+
+impl From<ExternalApiKeyCreateRecordInput> for crate::module_bindings::ExternalApiKeyCreateInput {
+    fn from(input: ExternalApiKeyCreateRecordInput) -> Self {
+        Self {
+            key_id: input.key_id,
+            owner_user_id: input.owner_user_id,
+            name: input.name,
+            key_prefix: input.key_prefix,
+            key_hash: input.key_hash,
+            scopes_json: serde_json::to_string(&input.scopes).unwrap_or_else(|_| "[]".to_string()),
+            now_micros: input.now_micros,
+        }
+    }
+}
+
+impl From<ExternalApiKeyRevokeRecordInput> for crate::module_bindings::ExternalApiKeyRevokeInput {
+    fn from(input: ExternalApiKeyRevokeRecordInput) -> Self {
+        Self {
+            key_id: input.key_id,
+            owner_user_id: input.owner_user_id,
+            revoked_at_micros: input.revoked_at_micros,
+        }
+    }
+}
+
+impl From<ExternalApiKeyAuthenticateRecordInput>
+    for crate::module_bindings::ExternalApiKeyAuthenticateInput
+{
+    fn from(input: ExternalApiKeyAuthenticateRecordInput) -> Self {
+        Self {
+            key_hash: input.key_hash,
+            used_at_micros: input.used_at_micros,
+        }
+    }
+}
+
+pub(crate) fn map_external_api_key_single_procedure_result(
+    result: ExternalApiKeyProcedureResult,
+) -> Result<ExternalApiKeyRecord, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .key
+        .map(map_external_api_key_snapshot)
+        .transpose()?
+        .ok_or_else(|| SpacetimeClientError::missing_snapshot("外部 API Key 快照"))
+}
+
+pub(crate) fn map_external_api_key_list_procedure_result(
+    result: ExternalApiKeyProcedureResult,
+) -> Result<Vec<ExternalApiKeyRecord>, SpacetimeClientError> {
+    if !result.ok {
+        return Err(SpacetimeClientError::procedure_failed(result.error_message));
+    }
+
+    result
+        .keys
+        .into_iter()
+        .map(map_external_api_key_snapshot)
+        .collect()
+}
+
+fn map_external_api_key_snapshot(
+    snapshot: ExternalApiKeySnapshot,
+) -> Result<ExternalApiKeyRecord, SpacetimeClientError> {
+    Ok(ExternalApiKeyRecord {
+        key_id: snapshot.key_id,
+        owner_user_id: snapshot.owner_user_id,
+        name: snapshot.name,
+        key_prefix: snapshot.key_prefix,
+        scopes: serde_json::from_str::<Vec<String>>(snapshot.scopes_json.as_str())
+            .map_err(SpacetimeClientError::validation_failed)?,
+        created_at: format_timestamp_micros(snapshot.created_at_micros),
+        last_used_at: snapshot.last_used_at_micros.map(format_timestamp_micros),
+        revoked_at: snapshot.revoked_at_micros.map(format_timestamp_micros),
+        updated_at: format_timestamp_micros(snapshot.updated_at_micros),
+    })
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings.rs b/server-rs/crates/spacetime-client/src/module_bindings.rs
index ec1ca8d2e..8d6885175 100644
--- a/server-rs/crates/spacetime-client/src/module_bindings.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings.rs
@@ -101,6 +101,7 @@ pub mod auth_store_snapshot_record_type;
 pub mod auth_store_snapshot_table;
 pub mod auth_store_snapshot_type;
 pub mod auth_store_snapshot_upsert_input_type;
+pub mod authenticate_external_api_key_and_return_procedure;
 pub mod authorize_database_migration_operator_procedure;
 pub mod bark_battle_draft_config_row_type;
 pub mod bark_battle_draft_config_snapshot_type;
@@ -236,6 +237,11 @@ pub mod create_battle_state_and_return_procedure;
 pub mod create_battle_state_reducer;
 pub mod create_big_fish_session_procedure;
 pub mod create_custom_world_agent_session_procedure;
+pub mod create_editor_asset_and_return_procedure;
+pub mod create_editor_asset_folder_and_return_procedure;
+pub mod create_editor_project_and_return_procedure;
+pub mod create_editor_project_resource_and_return_procedure;
+pub mod create_external_api_key_and_return_procedure;
 pub mod create_jump_hop_agent_session_procedure;
 pub mod create_match_3_d_agent_session_procedure;
 pub mod create_profile_recharge_order_and_return_procedure;
@@ -336,6 +342,9 @@ pub mod delete_bark_battle_work_procedure;
 pub mod delete_big_fish_work_procedure;
 pub mod delete_custom_world_agent_session_procedure;
 pub mod delete_custom_world_profile_and_return_procedure;
+pub mod delete_editor_asset_and_return_procedure;
+pub mod delete_editor_asset_folder_and_return_procedure;
+pub mod delete_editor_project_and_return_procedure;
 pub mod delete_jump_hop_work_procedure;
 pub mod delete_match_3_d_work_procedure;
 pub mod delete_puzzle_work_procedure;
@@ -345,12 +354,59 @@ pub mod delete_visual_novel_work_procedure;
 pub mod delete_wooden_fish_work_procedure;
 pub mod drag_puzzle_piece_or_group_procedure;
 pub mod drop_square_hole_shape_procedure;
+pub mod editor_asset_create_input_type;
+pub mod editor_asset_delete_input_type;
+pub mod editor_asset_folder_create_input_type;
+pub mod editor_asset_folder_delete_input_type;
+pub mod editor_asset_folder_procedure_result_type;
+pub mod editor_asset_folder_snapshot_type;
+pub mod editor_asset_folder_table;
+pub mod editor_asset_folder_type;
+pub mod editor_asset_folder_update_input_type;
+pub mod editor_asset_library_get_input_type;
+pub mod editor_asset_library_procedure_result_type;
+pub mod editor_asset_library_snapshot_type;
+pub mod editor_asset_procedure_result_type;
+pub mod editor_asset_snapshot_type;
+pub mod editor_asset_table;
+pub mod editor_asset_type;
+pub mod editor_asset_update_input_type;
+pub mod editor_canvas_snapshot_type;
+pub mod editor_canvas_table;
+pub mod editor_canvas_type;
+pub mod editor_project_create_input_type;
+pub mod editor_project_delete_input_type;
+pub mod editor_project_delete_procedure_result_type;
+pub mod editor_project_get_input_type;
+pub mod editor_project_get_recent_input_type;
+pub mod editor_project_layout_save_input_type;
+pub mod editor_project_list_input_type;
+pub mod editor_project_list_procedure_result_type;
+pub mod editor_project_procedure_result_type;
+pub mod editor_project_rename_input_type;
+pub mod editor_project_resource_create_input_type;
+pub mod editor_project_resource_procedure_result_type;
+pub mod editor_project_resource_snapshot_type;
+pub mod editor_project_resource_table;
+pub mod editor_project_resource_type;
+pub mod editor_project_snapshot_type;
+pub mod editor_project_table;
+pub mod editor_project_type;
+pub mod editor_project_viewport_snapshot_type;
 pub mod enqueue_external_generation_job_and_return_procedure;
 pub mod ensure_analytics_date_dimension_for_date_reducer;
 pub mod equip_inventory_item_input_type;
 pub mod execute_custom_world_agent_action_procedure;
 pub mod export_auth_store_snapshot_from_tables_procedure;
 pub mod export_database_migration_to_file_procedure;
+pub mod external_api_key_authenticate_input_type;
+pub mod external_api_key_create_input_type;
+pub mod external_api_key_list_input_type;
+pub mod external_api_key_procedure_result_type;
+pub mod external_api_key_revoke_input_type;
+pub mod external_api_key_snapshot_type;
+pub mod external_api_key_table;
+pub mod external_api_key_type;
 pub mod external_generation_job_claim_input_type;
 pub mod external_generation_job_complete_input_type;
 pub mod external_generation_job_enqueue_input_type;
@@ -389,6 +445,8 @@ pub mod get_custom_world_agent_session_procedure;
 pub mod get_custom_world_gallery_detail_by_code_procedure;
 pub mod get_custom_world_gallery_detail_procedure;
 pub mod get_custom_world_library_detail_procedure;
+pub mod get_editor_asset_library_and_return_procedure;
+pub mod get_editor_project_and_return_procedure;
 pub mod get_external_generation_job_and_return_procedure;
 pub mod get_external_generation_queue_stats_and_return_procedure;
 pub mod get_jump_hop_agent_session_procedure;
@@ -412,6 +470,7 @@ pub mod get_puzzle_clear_work_profile_procedure;
 pub mod get_puzzle_gallery_detail_procedure;
 pub mod get_puzzle_run_procedure;
 pub mod get_puzzle_work_detail_procedure;
+pub mod get_recent_editor_project_and_return_procedure;
 pub mod get_runtime_inventory_state_procedure;
 pub mod get_runtime_setting_or_default_procedure;
 pub mod get_runtime_snapshot_procedure;
@@ -500,6 +559,8 @@ pub mod list_big_fish_works_procedure;
 pub mod list_custom_world_gallery_entries_procedure;
 pub mod list_custom_world_profiles_procedure;
 pub mod list_custom_world_works_procedure;
+pub mod list_editor_projects_and_return_procedure;
+pub mod list_external_api_keys_and_return_procedure;
 pub mod list_jump_hop_works_procedure;
 pub mod list_match_3_d_works_procedure;
 pub mod list_platform_browse_history_procedure;
@@ -796,6 +857,7 @@ pub mod release_puzzle_background_compile_task_procedure;
 pub mod remix_big_fish_work_procedure;
 pub mod remix_custom_world_profile_procedure;
 pub mod remix_puzzle_work_procedure;
+pub mod rename_editor_project_and_return_procedure;
 pub mod renew_external_generation_job_lease_and_return_procedure;
 pub mod resolve_combat_action_and_return_procedure;
 pub mod resolve_combat_action_input_type;
@@ -818,6 +880,7 @@ pub mod restart_square_hole_run_procedure;
 pub mod resume_profile_save_archive_and_return_procedure;
 pub mod retry_puzzle_clear_level_run_procedure;
 pub mod revoke_database_migration_operator_procedure;
+pub mod revoke_external_api_key_and_return_procedure;
 pub mod rpg_agent_draft_card_kind_type;
 pub mod rpg_agent_draft_card_status_type;
 pub mod rpg_agent_message_kind_type;
@@ -934,6 +997,7 @@ pub mod runtime_tracking_event_batch_procedure_result_type;
 pub mod runtime_tracking_event_input_type;
 pub mod runtime_tracking_event_procedure_result_type;
 pub mod runtime_tracking_scope_kind_type;
+pub mod save_editor_project_layout_and_return_procedure;
 pub mod save_puzzle_form_draft_procedure;
 pub mod save_puzzle_generated_images_procedure;
 pub mod save_puzzle_ui_background_procedure;
@@ -1033,6 +1097,8 @@ pub mod unequip_inventory_item_input_type;
 pub mod unpublish_custom_world_profile_and_return_procedure;
 pub mod unpublish_custom_world_profile_reducer;
 pub mod update_bark_battle_draft_config_procedure;
+pub mod update_editor_asset_and_return_procedure;
+pub mod update_editor_asset_folder_and_return_procedure;
 pub mod update_jump_hop_work_procedure;
 pub mod update_match_3_d_work_procedure;
 pub mod update_puzzle_clear_work_procedure;
@@ -1237,6 +1303,7 @@ pub use auth_store_snapshot_record_type::AuthStoreSnapshotRecord;
 pub use auth_store_snapshot_table::*;
 pub use auth_store_snapshot_type::AuthStoreSnapshot;
 pub use auth_store_snapshot_upsert_input_type::AuthStoreSnapshotUpsertInput;
+pub use authenticate_external_api_key_and_return_procedure::authenticate_external_api_key_and_return;
 pub use authorize_database_migration_operator_procedure::authorize_database_migration_operator;
 pub use bark_battle_draft_config_row_type::BarkBattleDraftConfigRow;
 pub use bark_battle_draft_config_snapshot_type::BarkBattleDraftConfigSnapshot;
@@ -1372,6 +1439,11 @@ pub use create_battle_state_and_return_procedure::create_battle_state_and_return
 pub use create_battle_state_reducer::create_battle_state;
 pub use create_big_fish_session_procedure::create_big_fish_session;
 pub use create_custom_world_agent_session_procedure::create_custom_world_agent_session;
+pub use create_editor_asset_and_return_procedure::create_editor_asset_and_return;
+pub use create_editor_asset_folder_and_return_procedure::create_editor_asset_folder_and_return;
+pub use create_editor_project_and_return_procedure::create_editor_project_and_return;
+pub use create_editor_project_resource_and_return_procedure::create_editor_project_resource_and_return;
+pub use create_external_api_key_and_return_procedure::create_external_api_key_and_return;
 pub use create_jump_hop_agent_session_procedure::create_jump_hop_agent_session;
 pub use create_match_3_d_agent_session_procedure::create_match_3_d_agent_session;
 pub use create_profile_recharge_order_and_return_procedure::create_profile_recharge_order_and_return;
@@ -1472,6 +1544,9 @@ pub use delete_bark_battle_work_procedure::delete_bark_battle_work;
 pub use delete_big_fish_work_procedure::delete_big_fish_work;
 pub use delete_custom_world_agent_session_procedure::delete_custom_world_agent_session;
 pub use delete_custom_world_profile_and_return_procedure::delete_custom_world_profile_and_return;
+pub use delete_editor_asset_and_return_procedure::delete_editor_asset_and_return;
+pub use delete_editor_asset_folder_and_return_procedure::delete_editor_asset_folder_and_return;
+pub use delete_editor_project_and_return_procedure::delete_editor_project_and_return;
 pub use delete_jump_hop_work_procedure::delete_jump_hop_work;
 pub use delete_match_3_d_work_procedure::delete_match_3_d_work;
 pub use delete_puzzle_work_procedure::delete_puzzle_work;
@@ -1481,12 +1556,59 @@ pub use delete_visual_novel_work_procedure::delete_visual_novel_work;
 pub use delete_wooden_fish_work_procedure::delete_wooden_fish_work;
 pub use drag_puzzle_piece_or_group_procedure::drag_puzzle_piece_or_group;
 pub use drop_square_hole_shape_procedure::drop_square_hole_shape;
+pub use editor_asset_create_input_type::EditorAssetCreateInput;
+pub use editor_asset_delete_input_type::EditorAssetDeleteInput;
+pub use editor_asset_folder_create_input_type::EditorAssetFolderCreateInput;
+pub use editor_asset_folder_delete_input_type::EditorAssetFolderDeleteInput;
+pub use editor_asset_folder_procedure_result_type::EditorAssetFolderProcedureResult;
+pub use editor_asset_folder_snapshot_type::EditorAssetFolderSnapshot;
+pub use editor_asset_folder_table::*;
+pub use editor_asset_folder_type::EditorAssetFolder;
+pub use editor_asset_folder_update_input_type::EditorAssetFolderUpdateInput;
+pub use editor_asset_library_get_input_type::EditorAssetLibraryGetInput;
+pub use editor_asset_library_procedure_result_type::EditorAssetLibraryProcedureResult;
+pub use editor_asset_library_snapshot_type::EditorAssetLibrarySnapshot;
+pub use editor_asset_procedure_result_type::EditorAssetProcedureResult;
+pub use editor_asset_snapshot_type::EditorAssetSnapshot;
+pub use editor_asset_table::*;
+pub use editor_asset_type::EditorAsset;
+pub use editor_asset_update_input_type::EditorAssetUpdateInput;
+pub use editor_canvas_snapshot_type::EditorCanvasSnapshot;
+pub use editor_canvas_table::*;
+pub use editor_canvas_type::EditorCanvas;
+pub use editor_project_create_input_type::EditorProjectCreateInput;
+pub use editor_project_delete_input_type::EditorProjectDeleteInput;
+pub use editor_project_delete_procedure_result_type::EditorProjectDeleteProcedureResult;
+pub use editor_project_get_input_type::EditorProjectGetInput;
+pub use editor_project_get_recent_input_type::EditorProjectGetRecentInput;
+pub use editor_project_layout_save_input_type::EditorProjectLayoutSaveInput;
+pub use editor_project_list_input_type::EditorProjectListInput;
+pub use editor_project_list_procedure_result_type::EditorProjectListProcedureResult;
+pub use editor_project_procedure_result_type::EditorProjectProcedureResult;
+pub use editor_project_rename_input_type::EditorProjectRenameInput;
+pub use editor_project_resource_create_input_type::EditorProjectResourceCreateInput;
+pub use editor_project_resource_procedure_result_type::EditorProjectResourceProcedureResult;
+pub use editor_project_resource_snapshot_type::EditorProjectResourceSnapshot;
+pub use editor_project_resource_table::*;
+pub use editor_project_resource_type::EditorProjectResource;
+pub use editor_project_snapshot_type::EditorProjectSnapshot;
+pub use editor_project_table::*;
+pub use editor_project_type::EditorProject;
+pub use editor_project_viewport_snapshot_type::EditorProjectViewportSnapshot;
 pub use enqueue_external_generation_job_and_return_procedure::enqueue_external_generation_job_and_return;
 pub use ensure_analytics_date_dimension_for_date_reducer::ensure_analytics_date_dimension_for_date;
 pub use equip_inventory_item_input_type::EquipInventoryItemInput;
 pub use execute_custom_world_agent_action_procedure::execute_custom_world_agent_action;
 pub use export_auth_store_snapshot_from_tables_procedure::export_auth_store_snapshot_from_tables;
 pub use export_database_migration_to_file_procedure::export_database_migration_to_file;
+pub use external_api_key_authenticate_input_type::ExternalApiKeyAuthenticateInput;
+pub use external_api_key_create_input_type::ExternalApiKeyCreateInput;
+pub use external_api_key_list_input_type::ExternalApiKeyListInput;
+pub use external_api_key_procedure_result_type::ExternalApiKeyProcedureResult;
+pub use external_api_key_revoke_input_type::ExternalApiKeyRevokeInput;
+pub use external_api_key_snapshot_type::ExternalApiKeySnapshot;
+pub use external_api_key_table::*;
+pub use external_api_key_type::ExternalApiKey;
 pub use external_generation_job_claim_input_type::ExternalGenerationJobClaimInput;
 pub use external_generation_job_complete_input_type::ExternalGenerationJobCompleteInput;
 pub use external_generation_job_enqueue_input_type::ExternalGenerationJobEnqueueInput;
@@ -1525,6 +1647,8 @@ pub use get_custom_world_agent_session_procedure::get_custom_world_agent_session
 pub use get_custom_world_gallery_detail_by_code_procedure::get_custom_world_gallery_detail_by_code;
 pub use get_custom_world_gallery_detail_procedure::get_custom_world_gallery_detail;
 pub use get_custom_world_library_detail_procedure::get_custom_world_library_detail;
+pub use get_editor_asset_library_and_return_procedure::get_editor_asset_library_and_return;
+pub use get_editor_project_and_return_procedure::get_editor_project_and_return;
 pub use get_external_generation_job_and_return_procedure::get_external_generation_job_and_return;
 pub use get_external_generation_queue_stats_and_return_procedure::get_external_generation_queue_stats_and_return;
 pub use get_jump_hop_agent_session_procedure::get_jump_hop_agent_session;
@@ -1548,6 +1672,7 @@ pub use get_puzzle_clear_work_profile_procedure::get_puzzle_clear_work_profile;
 pub use get_puzzle_gallery_detail_procedure::get_puzzle_gallery_detail;
 pub use get_puzzle_run_procedure::get_puzzle_run;
 pub use get_puzzle_work_detail_procedure::get_puzzle_work_detail;
+pub use get_recent_editor_project_and_return_procedure::get_recent_editor_project_and_return;
 pub use get_runtime_inventory_state_procedure::get_runtime_inventory_state;
 pub use get_runtime_setting_or_default_procedure::get_runtime_setting_or_default;
 pub use get_runtime_snapshot_procedure::get_runtime_snapshot;
@@ -1636,6 +1761,8 @@ pub use list_big_fish_works_procedure::list_big_fish_works;
 pub use list_custom_world_gallery_entries_procedure::list_custom_world_gallery_entries;
 pub use list_custom_world_profiles_procedure::list_custom_world_profiles;
 pub use list_custom_world_works_procedure::list_custom_world_works;
+pub use list_editor_projects_and_return_procedure::list_editor_projects_and_return;
+pub use list_external_api_keys_and_return_procedure::list_external_api_keys_and_return;
 pub use list_jump_hop_works_procedure::list_jump_hop_works;
 pub use list_match_3_d_works_procedure::list_match_3_d_works;
 pub use list_platform_browse_history_procedure::list_platform_browse_history;
@@ -1932,6 +2059,7 @@ pub use release_puzzle_background_compile_task_procedure::release_puzzle_backgro
 pub use remix_big_fish_work_procedure::remix_big_fish_work;
 pub use remix_custom_world_profile_procedure::remix_custom_world_profile;
 pub use remix_puzzle_work_procedure::remix_puzzle_work;
+pub use rename_editor_project_and_return_procedure::rename_editor_project_and_return;
 pub use renew_external_generation_job_lease_and_return_procedure::renew_external_generation_job_lease_and_return;
 pub use resolve_combat_action_and_return_procedure::resolve_combat_action_and_return;
 pub use resolve_combat_action_input_type::ResolveCombatActionInput;
@@ -1954,6 +2082,7 @@ pub use restart_square_hole_run_procedure::restart_square_hole_run;
 pub use resume_profile_save_archive_and_return_procedure::resume_profile_save_archive_and_return;
 pub use retry_puzzle_clear_level_run_procedure::retry_puzzle_clear_level_run;
 pub use revoke_database_migration_operator_procedure::revoke_database_migration_operator;
+pub use revoke_external_api_key_and_return_procedure::revoke_external_api_key_and_return;
 pub use rpg_agent_draft_card_kind_type::RpgAgentDraftCardKind;
 pub use rpg_agent_draft_card_status_type::RpgAgentDraftCardStatus;
 pub use rpg_agent_message_kind_type::RpgAgentMessageKind;
@@ -2070,6 +2199,7 @@ pub use runtime_tracking_event_batch_procedure_result_type::RuntimeTrackingEvent
 pub use runtime_tracking_event_input_type::RuntimeTrackingEventInput;
 pub use runtime_tracking_event_procedure_result_type::RuntimeTrackingEventProcedureResult;
 pub use runtime_tracking_scope_kind_type::RuntimeTrackingScopeKind;
+pub use save_editor_project_layout_and_return_procedure::save_editor_project_layout_and_return;
 pub use save_puzzle_form_draft_procedure::save_puzzle_form_draft;
 pub use save_puzzle_generated_images_procedure::save_puzzle_generated_images;
 pub use save_puzzle_ui_background_procedure::save_puzzle_ui_background;
@@ -2169,6 +2299,8 @@ pub use unequip_inventory_item_input_type::UnequipInventoryItemInput;
 pub use unpublish_custom_world_profile_and_return_procedure::unpublish_custom_world_profile_and_return;
 pub use unpublish_custom_world_profile_reducer::unpublish_custom_world_profile;
 pub use update_bark_battle_draft_config_procedure::update_bark_battle_draft_config;
+pub use update_editor_asset_and_return_procedure::update_editor_asset_and_return;
+pub use update_editor_asset_folder_and_return_procedure::update_editor_asset_folder_and_return;
 pub use update_jump_hop_work_procedure::update_jump_hop_work;
 pub use update_match_3_d_work_procedure::update_match_3_d_work;
 pub use update_puzzle_clear_work_procedure::update_puzzle_clear_work;
@@ -2589,6 +2721,12 @@ pub struct DbUpdate {
     custom_world_session: __sdk::TableUpdate<CustomWorldSession>,
     database_migration_import_chunk: __sdk::TableUpdate<DatabaseMigrationImportChunk>,
     database_migration_operator: __sdk::TableUpdate<DatabaseMigrationOperator>,
+    editor_asset: __sdk::TableUpdate<EditorAsset>,
+    editor_asset_folder: __sdk::TableUpdate<EditorAssetFolder>,
+    editor_canvas: __sdk::TableUpdate<EditorCanvas>,
+    editor_project: __sdk::TableUpdate<EditorProject>,
+    editor_project_resource: __sdk::TableUpdate<EditorProjectResource>,
+    external_api_key: __sdk::TableUpdate<ExternalApiKey>,
     external_generation_job: __sdk::TableUpdate<ExternalGenerationJob>,
     inventory_slot: __sdk::TableUpdate<InventorySlot>,
     jump_hop_agent_session: __sdk::TableUpdate<JumpHopAgentSessionRow>,
@@ -2802,6 +2940,24 @@ impl TryFrom<__ws::v2::TransactionUpdate> for DbUpdate {
                 "database_migration_operator" => db_update.database_migration_operator.append(
                     database_migration_operator_table::parse_table_update(table_update)?,
                 ),
+                "editor_asset" => db_update
+                    .editor_asset
+                    .append(editor_asset_table::parse_table_update(table_update)?),
+                "editor_asset_folder" => db_update
+                    .editor_asset_folder
+                    .append(editor_asset_folder_table::parse_table_update(table_update)?),
+                "editor_canvas" => db_update
+                    .editor_canvas
+                    .append(editor_canvas_table::parse_table_update(table_update)?),
+                "editor_project" => db_update
+                    .editor_project
+                    .append(editor_project_table::parse_table_update(table_update)?),
+                "editor_project_resource" => db_update.editor_project_resource.append(
+                    editor_project_resource_table::parse_table_update(table_update)?,
+                ),
+                "external_api_key" => db_update
+                    .external_api_key
+                    .append(external_api_key_table::parse_table_update(table_update)?),
                 "external_generation_job" => db_update.external_generation_job.append(
                     external_generation_job_table::parse_table_update(table_update)?,
                 ),
@@ -3265,6 +3421,30 @@ impl __sdk::DbUpdate for DbUpdate {
                 &self.database_migration_operator,
             )
             .with_updates_by_pk(|row| &row.operator_identity);
+        diff.editor_asset = cache
+            .apply_diff_to_table::<EditorAsset>("editor_asset", &self.editor_asset)
+            .with_updates_by_pk(|row| &row.asset_id);
+        diff.editor_asset_folder = cache
+            .apply_diff_to_table::<EditorAssetFolder>(
+                "editor_asset_folder",
+                &self.editor_asset_folder,
+            )
+            .with_updates_by_pk(|row| &row.folder_id);
+        diff.editor_canvas = cache
+            .apply_diff_to_table::<EditorCanvas>("editor_canvas", &self.editor_canvas)
+            .with_updates_by_pk(|row| &row.canvas_id);
+        diff.editor_project = cache
+            .apply_diff_to_table::<EditorProject>("editor_project", &self.editor_project)
+            .with_updates_by_pk(|row| &row.project_id);
+        diff.editor_project_resource = cache
+            .apply_diff_to_table::<EditorProjectResource>(
+                "editor_project_resource",
+                &self.editor_project_resource,
+            )
+            .with_updates_by_pk(|row| &row.resource_id);
+        diff.external_api_key = cache
+            .apply_diff_to_table::<ExternalApiKey>("external_api_key", &self.external_api_key)
+            .with_updates_by_pk(|row| &row.key_id);
         diff.external_generation_job = cache
             .apply_diff_to_table::<ExternalGenerationJob>(
                 "external_generation_job",
@@ -3798,6 +3978,24 @@ impl __sdk::DbUpdate for DbUpdate {
                 "database_migration_operator" => db_update
                     .database_migration_operator
                     .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "editor_asset" => db_update
+                    .editor_asset
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "editor_asset_folder" => db_update
+                    .editor_asset_folder
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "editor_canvas" => db_update
+                    .editor_canvas
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "editor_project" => db_update
+                    .editor_project
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "editor_project_resource" => db_update
+                    .editor_project_resource
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
+                "external_api_key" => db_update
+                    .external_api_key
+                    .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
                 "external_generation_job" => db_update
                     .external_generation_job
                     .append(__sdk::parse_row_list_as_inserts(table_rows.rows)?),
@@ -4168,6 +4366,24 @@ impl __sdk::DbUpdate for DbUpdate {
                 "database_migration_operator" => db_update
                     .database_migration_operator
                     .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "editor_asset" => db_update
+                    .editor_asset
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "editor_asset_folder" => db_update
+                    .editor_asset_folder
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "editor_canvas" => db_update
+                    .editor_canvas
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "editor_project" => db_update
+                    .editor_project
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "editor_project_resource" => db_update
+                    .editor_project_resource
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
+                "external_api_key" => db_update
+                    .external_api_key
+                    .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
                 "external_generation_job" => db_update
                     .external_generation_job
                     .append(__sdk::parse_row_list_as_deletes(table_rows.rows)?),
@@ -4464,6 +4680,12 @@ pub struct AppliedDiff<'r> {
     custom_world_session: __sdk::TableAppliedDiff<'r, CustomWorldSession>,
     database_migration_import_chunk: __sdk::TableAppliedDiff<'r, DatabaseMigrationImportChunk>,
     database_migration_operator: __sdk::TableAppliedDiff<'r, DatabaseMigrationOperator>,
+    editor_asset: __sdk::TableAppliedDiff<'r, EditorAsset>,
+    editor_asset_folder: __sdk::TableAppliedDiff<'r, EditorAssetFolder>,
+    editor_canvas: __sdk::TableAppliedDiff<'r, EditorCanvas>,
+    editor_project: __sdk::TableAppliedDiff<'r, EditorProject>,
+    editor_project_resource: __sdk::TableAppliedDiff<'r, EditorProjectResource>,
+    external_api_key: __sdk::TableAppliedDiff<'r, ExternalApiKey>,
     external_generation_job: __sdk::TableAppliedDiff<'r, ExternalGenerationJob>,
     inventory_slot: __sdk::TableAppliedDiff<'r, InventorySlot>,
     jump_hop_agent_session: __sdk::TableAppliedDiff<'r, JumpHopAgentSessionRow>,
@@ -4745,6 +4967,36 @@ impl<'r> __sdk::AppliedDiff<'r> for AppliedDiff<'r> {
             &self.database_migration_operator,
             event,
         );
+        callbacks.invoke_table_row_callbacks::<EditorAsset>(
+            "editor_asset",
+            &self.editor_asset,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<EditorAssetFolder>(
+            "editor_asset_folder",
+            &self.editor_asset_folder,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<EditorCanvas>(
+            "editor_canvas",
+            &self.editor_canvas,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<EditorProject>(
+            "editor_project",
+            &self.editor_project,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<EditorProjectResource>(
+            "editor_project_resource",
+            &self.editor_project_resource,
+            event,
+        );
+        callbacks.invoke_table_row_callbacks::<ExternalApiKey>(
+            "external_api_key",
+            &self.external_api_key,
+            event,
+        );
         callbacks.invoke_table_row_callbacks::<ExternalGenerationJob>(
             "external_generation_job",
             &self.external_generation_job,
@@ -5832,6 +6084,12 @@ impl __sdk::SpacetimeModule for RemoteModule {
         custom_world_session_table::register_table(client_cache);
         database_migration_import_chunk_table::register_table(client_cache);
         database_migration_operator_table::register_table(client_cache);
+        editor_asset_table::register_table(client_cache);
+        editor_asset_folder_table::register_table(client_cache);
+        editor_canvas_table::register_table(client_cache);
+        editor_project_table::register_table(client_cache);
+        editor_project_resource_table::register_table(client_cache);
+        external_api_key_table::register_table(client_cache);
         external_generation_job_table::register_table(client_cache);
         inventory_slot_table::register_table(client_cache);
         jump_hop_agent_session_table::register_table(client_cache);
@@ -5953,6 +6211,12 @@ impl __sdk::SpacetimeModule for RemoteModule {
         "custom_world_session",
         "database_migration_import_chunk",
         "database_migration_operator",
+        "editor_asset",
+        "editor_asset_folder",
+        "editor_canvas",
+        "editor_project",
+        "editor_project_resource",
+        "external_api_key",
         "external_generation_job",
         "inventory_slot",
         "jump_hop_agent_session",
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/authenticate_external_api_key_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/authenticate_external_api_key_and_return_procedure.rs
new file mode 100644
index 000000000..4c3aec34c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/authenticate_external_api_key_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_api_key_authenticate_input_type::ExternalApiKeyAuthenticateInput;
+use super::external_api_key_procedure_result_type::ExternalApiKeyProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct AuthenticateExternalApiKeyAndReturnArgs {
+    pub input: ExternalApiKeyAuthenticateInput,
+}
+
+impl __sdk::InModule for AuthenticateExternalApiKeyAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `authenticate_external_api_key_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait authenticate_external_api_key_and_return {
+    fn authenticate_external_api_key_and_return(&self, input: ExternalApiKeyAuthenticateInput) {
+        self.authenticate_external_api_key_and_return_then(input, |_, _| {});
+    }
+
+    fn authenticate_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyAuthenticateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl authenticate_external_api_key_and_return for super::RemoteProcedures {
+    fn authenticate_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyAuthenticateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalApiKeyProcedureResult>(
+                "authenticate_external_api_key_and_return",
+                AuthenticateExternalApiKeyAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_and_return_procedure.rs
new file mode 100644
index 000000000..8ca475434
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_create_input_type::EditorAssetCreateInput;
+use super::editor_asset_procedure_result_type::EditorAssetProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateEditorAssetAndReturnArgs {
+    pub input: EditorAssetCreateInput,
+}
+
+impl __sdk::InModule for CreateEditorAssetAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_editor_asset_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_editor_asset_and_return {
+    fn create_editor_asset_and_return(&self, input: EditorAssetCreateInput) {
+        self.create_editor_asset_and_return_then(input, |_, _| {});
+    }
+
+    fn create_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_editor_asset_and_return for super::RemoteProcedures {
+    fn create_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetProcedureResult>(
+                "create_editor_asset_and_return",
+                CreateEditorAssetAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_folder_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_folder_and_return_procedure.rs
new file mode 100644
index 000000000..33ec7f85c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_asset_folder_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_folder_create_input_type::EditorAssetFolderCreateInput;
+use super::editor_asset_folder_procedure_result_type::EditorAssetFolderProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateEditorAssetFolderAndReturnArgs {
+    pub input: EditorAssetFolderCreateInput,
+}
+
+impl __sdk::InModule for CreateEditorAssetFolderAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_editor_asset_folder_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_editor_asset_folder_and_return {
+    fn create_editor_asset_folder_and_return(&self, input: EditorAssetFolderCreateInput) {
+        self.create_editor_asset_folder_and_return_then(input, |_, _| {});
+    }
+
+    fn create_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_editor_asset_folder_and_return for super::RemoteProcedures {
+    fn create_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetFolderProcedureResult>(
+                "create_editor_asset_folder_and_return",
+                CreateEditorAssetFolderAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_and_return_procedure.rs
new file mode 100644
index 000000000..7340d97d3
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_create_input_type::EditorProjectCreateInput;
+use super::editor_project_procedure_result_type::EditorProjectProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateEditorProjectAndReturnArgs {
+    pub input: EditorProjectCreateInput,
+}
+
+impl __sdk::InModule for CreateEditorProjectAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_editor_project_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_editor_project_and_return {
+    fn create_editor_project_and_return(&self, input: EditorProjectCreateInput) {
+        self.create_editor_project_and_return_then(input, |_, _| {});
+    }
+
+    fn create_editor_project_and_return_then(
+        &self,
+        input: EditorProjectCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_editor_project_and_return for super::RemoteProcedures {
+    fn create_editor_project_and_return_then(
+        &self,
+        input: EditorProjectCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectProcedureResult>(
+                "create_editor_project_and_return",
+                CreateEditorProjectAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_resource_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_resource_and_return_procedure.rs
new file mode 100644
index 000000000..649d2a3e0
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_editor_project_resource_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_resource_create_input_type::EditorProjectResourceCreateInput;
+use super::editor_project_resource_procedure_result_type::EditorProjectResourceProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateEditorProjectResourceAndReturnArgs {
+    pub input: EditorProjectResourceCreateInput,
+}
+
+impl __sdk::InModule for CreateEditorProjectResourceAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_editor_project_resource_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_editor_project_resource_and_return {
+    fn create_editor_project_resource_and_return(&self, input: EditorProjectResourceCreateInput) {
+        self.create_editor_project_resource_and_return_then(input, |_, _| {});
+    }
+
+    fn create_editor_project_resource_and_return_then(
+        &self,
+        input: EditorProjectResourceCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectResourceProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_editor_project_resource_and_return for super::RemoteProcedures {
+    fn create_editor_project_resource_and_return_then(
+        &self,
+        input: EditorProjectResourceCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectResourceProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectResourceProcedureResult>(
+                "create_editor_project_resource_and_return",
+                CreateEditorProjectResourceAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/create_external_api_key_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/create_external_api_key_and_return_procedure.rs
new file mode 100644
index 000000000..daf4a676f
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/create_external_api_key_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_api_key_create_input_type::ExternalApiKeyCreateInput;
+use super::external_api_key_procedure_result_type::ExternalApiKeyProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct CreateExternalApiKeyAndReturnArgs {
+    pub input: ExternalApiKeyCreateInput,
+}
+
+impl __sdk::InModule for CreateExternalApiKeyAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `create_external_api_key_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait create_external_api_key_and_return {
+    fn create_external_api_key_and_return(&self, input: ExternalApiKeyCreateInput) {
+        self.create_external_api_key_and_return_then(input, |_, _| {});
+    }
+
+    fn create_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl create_external_api_key_and_return for super::RemoteProcedures {
+    fn create_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyCreateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalApiKeyProcedureResult>(
+                "create_external_api_key_and_return",
+                CreateExternalApiKeyAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_and_return_procedure.rs
new file mode 100644
index 000000000..4c71ecd53
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_delete_input_type::EditorAssetDeleteInput;
+use super::editor_asset_procedure_result_type::EditorAssetProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct DeleteEditorAssetAndReturnArgs {
+    pub input: EditorAssetDeleteInput,
+}
+
+impl __sdk::InModule for DeleteEditorAssetAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `delete_editor_asset_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait delete_editor_asset_and_return {
+    fn delete_editor_asset_and_return(&self, input: EditorAssetDeleteInput) {
+        self.delete_editor_asset_and_return_then(input, |_, _| {});
+    }
+
+    fn delete_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl delete_editor_asset_and_return for super::RemoteProcedures {
+    fn delete_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetProcedureResult>(
+                "delete_editor_asset_and_return",
+                DeleteEditorAssetAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_folder_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_folder_and_return_procedure.rs
new file mode 100644
index 000000000..6500a7c79
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_asset_folder_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_folder_delete_input_type::EditorAssetFolderDeleteInput;
+use super::editor_asset_folder_procedure_result_type::EditorAssetFolderProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct DeleteEditorAssetFolderAndReturnArgs {
+    pub input: EditorAssetFolderDeleteInput,
+}
+
+impl __sdk::InModule for DeleteEditorAssetFolderAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `delete_editor_asset_folder_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait delete_editor_asset_folder_and_return {
+    fn delete_editor_asset_folder_and_return(&self, input: EditorAssetFolderDeleteInput) {
+        self.delete_editor_asset_folder_and_return_then(input, |_, _| {});
+    }
+
+    fn delete_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl delete_editor_asset_folder_and_return for super::RemoteProcedures {
+    fn delete_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetFolderProcedureResult>(
+                "delete_editor_asset_folder_and_return",
+                DeleteEditorAssetFolderAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_project_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_project_and_return_procedure.rs
new file mode 100644
index 000000000..529aec929
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/delete_editor_project_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_delete_input_type::EditorProjectDeleteInput;
+use super::editor_project_delete_procedure_result_type::EditorProjectDeleteProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct DeleteEditorProjectAndReturnArgs {
+    pub input: EditorProjectDeleteInput,
+}
+
+impl __sdk::InModule for DeleteEditorProjectAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `delete_editor_project_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait delete_editor_project_and_return {
+    fn delete_editor_project_and_return(&self, input: EditorProjectDeleteInput) {
+        self.delete_editor_project_and_return_then(input, |_, _| {});
+    }
+
+    fn delete_editor_project_and_return_then(
+        &self,
+        input: EditorProjectDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectDeleteProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl delete_editor_project_and_return for super::RemoteProcedures {
+    fn delete_editor_project_and_return_then(
+        &self,
+        input: EditorProjectDeleteInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectDeleteProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectDeleteProcedureResult>(
+                "delete_editor_project_and_return",
+                DeleteEditorProjectAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_create_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_create_input_type.rs
new file mode 100644
index 000000000..f37faf5d1
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_create_input_type.rs
@@ -0,0 +1,32 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetCreateInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetCreateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_delete_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_delete_input_type.rs
new file mode 100644
index 000000000..98f46bd6b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_delete_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetDeleteInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for EditorAssetDeleteInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_create_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_create_input_type.rs
new file mode 100644
index 000000000..91b85d8cf
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_create_input_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolderCreateInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetFolderCreateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_delete_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_delete_input_type.rs
new file mode 100644
index 000000000..aecacc936
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_delete_input_type.rs
@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolderDeleteInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetFolderDeleteInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_procedure_result_type.rs
new file mode 100644
index 000000000..5507cb7d6
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_procedure_result_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_folder_snapshot_type::EditorAssetFolderSnapshot;
+use super::editor_asset_library_snapshot_type::EditorAssetLibrarySnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolderProcedureResult {
+    pub ok: bool,
+    pub folder: Option<EditorAssetFolderSnapshot>,
+    pub library: Option<EditorAssetLibrarySnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorAssetFolderProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_snapshot_type.rs
new file mode 100644
index 000000000..193ce49f4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_snapshot_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolderSnapshot {
+    pub folder_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub collapsed: bool,
+    pub system_default: bool,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetFolderSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_table.rs
new file mode 100644
index 000000000..d90c63756
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_table.rs
@@ -0,0 +1,161 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::editor_asset_folder_type::EditorAssetFolder;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `editor_asset_folder`.
+///
+/// Obtain a handle from the [`EditorAssetFolderTableAccess::editor_asset_folder`] method on [`super::RemoteTables`],
+/// like `ctx.db.editor_asset_folder()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_asset_folder().on_insert(...)`.
+pub struct EditorAssetFolderTableHandle<'ctx> {
+    imp: __sdk::TableHandle<EditorAssetFolder>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `editor_asset_folder`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait EditorAssetFolderTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`EditorAssetFolderTableHandle`], which mediates access to the table `editor_asset_folder`.
+    fn editor_asset_folder(&self) -> EditorAssetFolderTableHandle<'_>;
+}
+
+impl EditorAssetFolderTableAccess for super::RemoteTables {
+    fn editor_asset_folder(&self) -> EditorAssetFolderTableHandle<'_> {
+        EditorAssetFolderTableHandle {
+            imp: self
+                .imp
+                .get_table::<EditorAssetFolder>("editor_asset_folder"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct EditorAssetFolderInsertCallbackId(__sdk::CallbackId);
+pub struct EditorAssetFolderDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for EditorAssetFolderTableHandle<'ctx> {
+    type Row = EditorAssetFolder;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = EditorAssetFolder> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = EditorAssetFolderInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorAssetFolderInsertCallbackId {
+        EditorAssetFolderInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: EditorAssetFolderInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = EditorAssetFolderDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorAssetFolderDeleteCallbackId {
+        EditorAssetFolderDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: EditorAssetFolderDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct EditorAssetFolderUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for EditorAssetFolderTableHandle<'ctx> {
+    type UpdateCallbackId = EditorAssetFolderUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> EditorAssetFolderUpdateCallbackId {
+        EditorAssetFolderUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: EditorAssetFolderUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `folder_id` unique index on the table `editor_asset_folder`,
+/// which allows point queries on the field of the same name
+/// via the [`EditorAssetFolderFolderIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_asset_folder().folder_id().find(...)`.
+pub struct EditorAssetFolderFolderIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<EditorAssetFolder, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> EditorAssetFolderTableHandle<'ctx> {
+    /// Get a handle on the `folder_id` unique index on the table `editor_asset_folder`.
+    pub fn folder_id(&self) -> EditorAssetFolderFolderIdUnique<'ctx> {
+        EditorAssetFolderFolderIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("folder_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> EditorAssetFolderFolderIdUnique<'ctx> {
+    /// Find the subscribed row whose `folder_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<EditorAssetFolder> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<EditorAssetFolder>("editor_asset_folder");
+    _table.add_unique_constraint::<String>("folder_id", |row| &row.folder_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<EditorAssetFolder>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<EditorAssetFolder>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `EditorAssetFolder`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait editor_asset_folderQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `EditorAssetFolder`.
+    fn editor_asset_folder(&self) -> __sdk::__query_builder::Table<EditorAssetFolder>;
+}
+
+impl editor_asset_folderQueryTableAccess for __sdk::QueryTableAccessor {
+    fn editor_asset_folder(&self) -> __sdk::__query_builder::Table<EditorAssetFolder> {
+        __sdk::__query_builder::Table::new("editor_asset_folder")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_type.rs
new file mode 100644
index 000000000..70b838d7c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_type.rs
@@ -0,0 +1,72 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolder {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub collapsed: bool,
+    pub system_default: bool,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+}
+
+impl __sdk::InModule for EditorAssetFolder {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `EditorAssetFolder`.
+///
+/// Provides typed access to columns for query building.
+pub struct EditorAssetFolderCols {
+    pub folder_id: __sdk::__query_builder::Col<EditorAssetFolder, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<EditorAssetFolder, String>,
+    pub label: __sdk::__query_builder::Col<EditorAssetFolder, String>,
+    pub sort_order: __sdk::__query_builder::Col<EditorAssetFolder, u32>,
+    pub collapsed: __sdk::__query_builder::Col<EditorAssetFolder, bool>,
+    pub system_default: __sdk::__query_builder::Col<EditorAssetFolder, bool>,
+    pub created_at: __sdk::__query_builder::Col<EditorAssetFolder, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<EditorAssetFolder, __sdk::Timestamp>,
+}
+
+impl __sdk::__query_builder::HasCols for EditorAssetFolder {
+    type Cols = EditorAssetFolderCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        EditorAssetFolderCols {
+            folder_id: __sdk::__query_builder::Col::new(table_name, "folder_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            label: __sdk::__query_builder::Col::new(table_name, "label"),
+            sort_order: __sdk::__query_builder::Col::new(table_name, "sort_order"),
+            collapsed: __sdk::__query_builder::Col::new(table_name, "collapsed"),
+            system_default: __sdk::__query_builder::Col::new(table_name, "system_default"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `EditorAssetFolder`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct EditorAssetFolderIxCols {
+    pub folder_id: __sdk::__query_builder::IxCol<EditorAssetFolder, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<EditorAssetFolder, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for EditorAssetFolder {
+    type IxCols = EditorAssetFolderIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        EditorAssetFolderIxCols {
+            folder_id: __sdk::__query_builder::IxCol::new(table_name, "folder_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for EditorAssetFolder {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_update_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_update_input_type.rs
new file mode 100644
index 000000000..9004985cb
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_folder_update_input_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetFolderUpdateInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub collapsed: Option<bool>,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetFolderUpdateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_get_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_get_input_type.rs
new file mode 100644
index 000000000..c26a3223b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_get_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetLibraryGetInput {
+    pub owner_user_id: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetLibraryGetInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_procedure_result_type.rs
new file mode 100644
index 000000000..3238b319d
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_library_snapshot_type::EditorAssetLibrarySnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetLibraryProcedureResult {
+    pub ok: bool,
+    pub library: Option<EditorAssetLibrarySnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorAssetLibraryProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_snapshot_type.rs
new file mode 100644
index 000000000..6c59ede1f
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_library_snapshot_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_folder_snapshot_type::EditorAssetFolderSnapshot;
+use super::editor_asset_snapshot_type::EditorAssetSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetLibrarySnapshot {
+    pub folders: Vec<EditorAssetFolderSnapshot>,
+    pub assets: Vec<EditorAssetSnapshot>,
+}
+
+impl __sdk::InModule for EditorAssetLibrarySnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_procedure_result_type.rs
new file mode 100644
index 000000000..e8de2959e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_snapshot_type::EditorAssetSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetProcedureResult {
+    pub ok: bool,
+    pub asset: Option<EditorAssetSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorAssetProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_snapshot_type.rs
new file mode 100644
index 000000000..85cb1de4a
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_snapshot_type.rs
@@ -0,0 +1,32 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetSnapshot {
+    pub asset_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_table.rs
new file mode 100644
index 000000000..2bb93bb2c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_table.rs
@@ -0,0 +1,159 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::editor_asset_type::EditorAsset;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `editor_asset`.
+///
+/// Obtain a handle from the [`EditorAssetTableAccess::editor_asset`] method on [`super::RemoteTables`],
+/// like `ctx.db.editor_asset()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_asset().on_insert(...)`.
+pub struct EditorAssetTableHandle<'ctx> {
+    imp: __sdk::TableHandle<EditorAsset>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `editor_asset`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait EditorAssetTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`EditorAssetTableHandle`], which mediates access to the table `editor_asset`.
+    fn editor_asset(&self) -> EditorAssetTableHandle<'_>;
+}
+
+impl EditorAssetTableAccess for super::RemoteTables {
+    fn editor_asset(&self) -> EditorAssetTableHandle<'_> {
+        EditorAssetTableHandle {
+            imp: self.imp.get_table::<EditorAsset>("editor_asset"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct EditorAssetInsertCallbackId(__sdk::CallbackId);
+pub struct EditorAssetDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for EditorAssetTableHandle<'ctx> {
+    type Row = EditorAsset;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = EditorAsset> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = EditorAssetInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorAssetInsertCallbackId {
+        EditorAssetInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: EditorAssetInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = EditorAssetDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorAssetDeleteCallbackId {
+        EditorAssetDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: EditorAssetDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct EditorAssetUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for EditorAssetTableHandle<'ctx> {
+    type UpdateCallbackId = EditorAssetUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> EditorAssetUpdateCallbackId {
+        EditorAssetUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: EditorAssetUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `asset_id` unique index on the table `editor_asset`,
+/// which allows point queries on the field of the same name
+/// via the [`EditorAssetAssetIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_asset().asset_id().find(...)`.
+pub struct EditorAssetAssetIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<EditorAsset, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> EditorAssetTableHandle<'ctx> {
+    /// Get a handle on the `asset_id` unique index on the table `editor_asset`.
+    pub fn asset_id(&self) -> EditorAssetAssetIdUnique<'ctx> {
+        EditorAssetAssetIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("asset_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> EditorAssetAssetIdUnique<'ctx> {
+    /// Find the subscribed row whose `asset_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<EditorAsset> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<EditorAsset>("editor_asset");
+    _table.add_unique_constraint::<String>("asset_id", |row| &row.asset_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<EditorAsset>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<EditorAsset>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `EditorAsset`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait editor_assetQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `EditorAsset`.
+    fn editor_asset(&self) -> __sdk::__query_builder::Table<EditorAsset>;
+}
+
+impl editor_assetQueryTableAccess for __sdk::QueryTableAccessor {
+    fn editor_asset(&self) -> __sdk::__query_builder::Table<EditorAsset> {
+        __sdk::__query_builder::Table::new("editor_asset")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_type.rs
new file mode 100644
index 000000000..04e959907
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_type.rs
@@ -0,0 +1,110 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAsset {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+}
+
+impl __sdk::InModule for EditorAsset {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `EditorAsset`.
+///
+/// Provides typed access to columns for query building.
+pub struct EditorAssetCols {
+    pub asset_id: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub folder_id: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub label: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub asset_object_id: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub image_src: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub object_key: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub width: __sdk::__query_builder::Col<EditorAsset, u32>,
+    pub height: __sdk::__query_builder::Col<EditorAsset, u32>,
+    pub source_type: __sdk::__query_builder::Col<EditorAsset, String>,
+    pub prompt: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub actual_prompt: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub model: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub provider: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub task_id: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub created_at: __sdk::__query_builder::Col<EditorAsset, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<EditorAsset, __sdk::Timestamp>,
+    pub asset_kind: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+    pub generation_inputs_json: __sdk::__query_builder::Col<EditorAsset, Option<String>>,
+}
+
+impl __sdk::__query_builder::HasCols for EditorAsset {
+    type Cols = EditorAssetCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        EditorAssetCols {
+            asset_id: __sdk::__query_builder::Col::new(table_name, "asset_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            folder_id: __sdk::__query_builder::Col::new(table_name, "folder_id"),
+            label: __sdk::__query_builder::Col::new(table_name, "label"),
+            asset_object_id: __sdk::__query_builder::Col::new(table_name, "asset_object_id"),
+            image_src: __sdk::__query_builder::Col::new(table_name, "image_src"),
+            object_key: __sdk::__query_builder::Col::new(table_name, "object_key"),
+            width: __sdk::__query_builder::Col::new(table_name, "width"),
+            height: __sdk::__query_builder::Col::new(table_name, "height"),
+            source_type: __sdk::__query_builder::Col::new(table_name, "source_type"),
+            prompt: __sdk::__query_builder::Col::new(table_name, "prompt"),
+            actual_prompt: __sdk::__query_builder::Col::new(table_name, "actual_prompt"),
+            model: __sdk::__query_builder::Col::new(table_name, "model"),
+            provider: __sdk::__query_builder::Col::new(table_name, "provider"),
+            task_id: __sdk::__query_builder::Col::new(table_name, "task_id"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            asset_kind: __sdk::__query_builder::Col::new(table_name, "asset_kind"),
+            generation_inputs_json: __sdk::__query_builder::Col::new(
+                table_name,
+                "generation_inputs_json",
+            ),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `EditorAsset`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct EditorAssetIxCols {
+    pub asset_id: __sdk::__query_builder::IxCol<EditorAsset, String>,
+    pub folder_id: __sdk::__query_builder::IxCol<EditorAsset, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<EditorAsset, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for EditorAsset {
+    type IxCols = EditorAssetIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        EditorAssetIxCols {
+            asset_id: __sdk::__query_builder::IxCol::new(table_name, "asset_id"),
+            folder_id: __sdk::__query_builder::IxCol::new(table_name, "folder_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for EditorAsset {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_update_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_update_input_type.rs
new file mode 100644
index 000000000..950222db3
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_asset_update_input_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorAssetUpdateInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub folder_id: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorAssetUpdateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_snapshot_type.rs
new file mode 100644
index 000000000..a11f1bb4c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_snapshot_type.rs
@@ -0,0 +1,23 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_viewport_snapshot_type::EditorProjectViewportSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorCanvasSnapshot {
+    pub canvas_id: String,
+    pub project_id: String,
+    pub title: String,
+    pub viewport: EditorProjectViewportSnapshot,
+    pub layers_json: String,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorCanvasSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_table.rs
new file mode 100644
index 000000000..6e0eb9c8e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_table.rs
@@ -0,0 +1,159 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::editor_canvas_type::EditorCanvas;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `editor_canvas`.
+///
+/// Obtain a handle from the [`EditorCanvasTableAccess::editor_canvas`] method on [`super::RemoteTables`],
+/// like `ctx.db.editor_canvas()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_canvas().on_insert(...)`.
+pub struct EditorCanvasTableHandle<'ctx> {
+    imp: __sdk::TableHandle<EditorCanvas>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `editor_canvas`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait EditorCanvasTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`EditorCanvasTableHandle`], which mediates access to the table `editor_canvas`.
+    fn editor_canvas(&self) -> EditorCanvasTableHandle<'_>;
+}
+
+impl EditorCanvasTableAccess for super::RemoteTables {
+    fn editor_canvas(&self) -> EditorCanvasTableHandle<'_> {
+        EditorCanvasTableHandle {
+            imp: self.imp.get_table::<EditorCanvas>("editor_canvas"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct EditorCanvasInsertCallbackId(__sdk::CallbackId);
+pub struct EditorCanvasDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for EditorCanvasTableHandle<'ctx> {
+    type Row = EditorCanvas;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = EditorCanvas> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = EditorCanvasInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorCanvasInsertCallbackId {
+        EditorCanvasInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: EditorCanvasInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = EditorCanvasDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorCanvasDeleteCallbackId {
+        EditorCanvasDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: EditorCanvasDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct EditorCanvasUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for EditorCanvasTableHandle<'ctx> {
+    type UpdateCallbackId = EditorCanvasUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> EditorCanvasUpdateCallbackId {
+        EditorCanvasUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: EditorCanvasUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `canvas_id` unique index on the table `editor_canvas`,
+/// which allows point queries on the field of the same name
+/// via the [`EditorCanvasCanvasIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_canvas().canvas_id().find(...)`.
+pub struct EditorCanvasCanvasIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<EditorCanvas, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> EditorCanvasTableHandle<'ctx> {
+    /// Get a handle on the `canvas_id` unique index on the table `editor_canvas`.
+    pub fn canvas_id(&self) -> EditorCanvasCanvasIdUnique<'ctx> {
+        EditorCanvasCanvasIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("canvas_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> EditorCanvasCanvasIdUnique<'ctx> {
+    /// Find the subscribed row whose `canvas_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<EditorCanvas> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<EditorCanvas>("editor_canvas");
+    _table.add_unique_constraint::<String>("canvas_id", |row| &row.canvas_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<EditorCanvas>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<EditorCanvas>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `EditorCanvas`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait editor_canvasQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `EditorCanvas`.
+    fn editor_canvas(&self) -> __sdk::__query_builder::Table<EditorCanvas>;
+}
+
+impl editor_canvasQueryTableAccess for __sdk::QueryTableAccessor {
+    fn editor_canvas(&self) -> __sdk::__query_builder::Table<EditorCanvas> {
+        __sdk::__query_builder::Table::new("editor_canvas")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_type.rs
new file mode 100644
index 000000000..0854e6adc
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_canvas_type.rs
@@ -0,0 +1,80 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorCanvas {
+    pub canvas_id: String,
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub viewport_x: f64,
+    pub viewport_y: f64,
+    pub viewport_scale: f64,
+    pub layers_json: String,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+}
+
+impl __sdk::InModule for EditorCanvas {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `EditorCanvas`.
+///
+/// Provides typed access to columns for query building.
+pub struct EditorCanvasCols {
+    pub canvas_id: __sdk::__query_builder::Col<EditorCanvas, String>,
+    pub project_id: __sdk::__query_builder::Col<EditorCanvas, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<EditorCanvas, String>,
+    pub title: __sdk::__query_builder::Col<EditorCanvas, String>,
+    pub viewport_x: __sdk::__query_builder::Col<EditorCanvas, f64>,
+    pub viewport_y: __sdk::__query_builder::Col<EditorCanvas, f64>,
+    pub viewport_scale: __sdk::__query_builder::Col<EditorCanvas, f64>,
+    pub layers_json: __sdk::__query_builder::Col<EditorCanvas, String>,
+    pub created_at: __sdk::__query_builder::Col<EditorCanvas, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<EditorCanvas, __sdk::Timestamp>,
+}
+
+impl __sdk::__query_builder::HasCols for EditorCanvas {
+    type Cols = EditorCanvasCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        EditorCanvasCols {
+            canvas_id: __sdk::__query_builder::Col::new(table_name, "canvas_id"),
+            project_id: __sdk::__query_builder::Col::new(table_name, "project_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            title: __sdk::__query_builder::Col::new(table_name, "title"),
+            viewport_x: __sdk::__query_builder::Col::new(table_name, "viewport_x"),
+            viewport_y: __sdk::__query_builder::Col::new(table_name, "viewport_y"),
+            viewport_scale: __sdk::__query_builder::Col::new(table_name, "viewport_scale"),
+            layers_json: __sdk::__query_builder::Col::new(table_name, "layers_json"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `EditorCanvas`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct EditorCanvasIxCols {
+    pub canvas_id: __sdk::__query_builder::IxCol<EditorCanvas, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<EditorCanvas, String>,
+    pub project_id: __sdk::__query_builder::IxCol<EditorCanvas, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for EditorCanvas {
+    type IxCols = EditorCanvasIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        EditorCanvasIxCols {
+            canvas_id: __sdk::__query_builder::IxCol::new(table_name, "canvas_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+            project_id: __sdk::__query_builder::IxCol::new(table_name, "project_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for EditorCanvas {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_create_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_create_input_type.rs
new file mode 100644
index 000000000..7c6d0bde4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_create_input_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectCreateInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectCreateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_input_type.rs
new file mode 100644
index 000000000..0a173f913
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectDeleteInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for EditorProjectDeleteInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_procedure_result_type.rs
new file mode 100644
index 000000000..bf9e00c0e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_delete_procedure_result_type.rs
@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectDeleteProcedureResult {
+    pub ok: bool,
+    pub deleted_project_id: Option<String>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorProjectDeleteProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_input_type.rs
new file mode 100644
index 000000000..23b6e1da4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectGetInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for EditorProjectGetInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_recent_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_recent_input_type.rs
new file mode 100644
index 000000000..50d185dbf
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_get_recent_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectGetRecentInput {
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for EditorProjectGetRecentInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_layout_save_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_layout_save_input_type.rs
new file mode 100644
index 000000000..5d2b92106
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_layout_save_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_viewport_snapshot_type::EditorProjectViewportSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectLayoutSaveInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub viewport: EditorProjectViewportSnapshot,
+    pub layers_json: String,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectLayoutSaveInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_input_type.rs
new file mode 100644
index 000000000..71b4c172c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectListInput {
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for EditorProjectListInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_procedure_result_type.rs
new file mode 100644
index 000000000..bc02124bf
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_list_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_snapshot_type::EditorProjectSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectListProcedureResult {
+    pub ok: bool,
+    pub projects: Vec<EditorProjectSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorProjectListProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_procedure_result_type.rs
new file mode 100644
index 000000000..a71563752
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_snapshot_type::EditorProjectSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectProcedureResult {
+    pub ok: bool,
+    pub project: Option<EditorProjectSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorProjectProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_rename_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_rename_input_type.rs
new file mode 100644
index 000000000..de1c6e821
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_rename_input_type.rs
@@ -0,0 +1,18 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectRenameInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectRenameInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_create_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_create_input_type.rs
new file mode 100644
index 000000000..cac8c3376
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_create_input_type.rs
@@ -0,0 +1,32 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectResourceCreateInput {
+    pub resource_id: String,
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectResourceCreateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_procedure_result_type.rs
new file mode 100644
index 000000000..cee646459
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_procedure_result_type.rs
@@ -0,0 +1,19 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_resource_snapshot_type::EditorProjectResourceSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectResourceProcedureResult {
+    pub ok: bool,
+    pub resource: Option<EditorProjectResourceSnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for EditorProjectResourceProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_snapshot_type.rs
new file mode 100644
index 000000000..085ff2b4c
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_snapshot_type.rs
@@ -0,0 +1,32 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectResourceSnapshot {
+    pub resource_id: String,
+    pub project_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectResourceSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_table.rs
new file mode 100644
index 000000000..47208d830
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_table.rs
@@ -0,0 +1,161 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::editor_project_resource_type::EditorProjectResource;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `editor_project_resource`.
+///
+/// Obtain a handle from the [`EditorProjectResourceTableAccess::editor_project_resource`] method on [`super::RemoteTables`],
+/// like `ctx.db.editor_project_resource()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_project_resource().on_insert(...)`.
+pub struct EditorProjectResourceTableHandle<'ctx> {
+    imp: __sdk::TableHandle<EditorProjectResource>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `editor_project_resource`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait EditorProjectResourceTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`EditorProjectResourceTableHandle`], which mediates access to the table `editor_project_resource`.
+    fn editor_project_resource(&self) -> EditorProjectResourceTableHandle<'_>;
+}
+
+impl EditorProjectResourceTableAccess for super::RemoteTables {
+    fn editor_project_resource(&self) -> EditorProjectResourceTableHandle<'_> {
+        EditorProjectResourceTableHandle {
+            imp: self
+                .imp
+                .get_table::<EditorProjectResource>("editor_project_resource"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct EditorProjectResourceInsertCallbackId(__sdk::CallbackId);
+pub struct EditorProjectResourceDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for EditorProjectResourceTableHandle<'ctx> {
+    type Row = EditorProjectResource;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = EditorProjectResource> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = EditorProjectResourceInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorProjectResourceInsertCallbackId {
+        EditorProjectResourceInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: EditorProjectResourceInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = EditorProjectResourceDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorProjectResourceDeleteCallbackId {
+        EditorProjectResourceDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: EditorProjectResourceDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct EditorProjectResourceUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for EditorProjectResourceTableHandle<'ctx> {
+    type UpdateCallbackId = EditorProjectResourceUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> EditorProjectResourceUpdateCallbackId {
+        EditorProjectResourceUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: EditorProjectResourceUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `resource_id` unique index on the table `editor_project_resource`,
+/// which allows point queries on the field of the same name
+/// via the [`EditorProjectResourceResourceIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_project_resource().resource_id().find(...)`.
+pub struct EditorProjectResourceResourceIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<EditorProjectResource, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> EditorProjectResourceTableHandle<'ctx> {
+    /// Get a handle on the `resource_id` unique index on the table `editor_project_resource`.
+    pub fn resource_id(&self) -> EditorProjectResourceResourceIdUnique<'ctx> {
+        EditorProjectResourceResourceIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("resource_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> EditorProjectResourceResourceIdUnique<'ctx> {
+    /// Find the subscribed row whose `resource_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<EditorProjectResource> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<EditorProjectResource>("editor_project_resource");
+    _table.add_unique_constraint::<String>("resource_id", |row| &row.resource_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<EditorProjectResource>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<EditorProjectResource>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `EditorProjectResource`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait editor_project_resourceQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `EditorProjectResource`.
+    fn editor_project_resource(&self) -> __sdk::__query_builder::Table<EditorProjectResource>;
+}
+
+impl editor_project_resourceQueryTableAccess for __sdk::QueryTableAccessor {
+    fn editor_project_resource(&self) -> __sdk::__query_builder::Table<EditorProjectResource> {
+        __sdk::__query_builder::Table::new("editor_project_resource")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_type.rs
new file mode 100644
index 000000000..a47526ce4
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_resource_type.rs
@@ -0,0 +1,110 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectResource {
+    pub resource_id: String,
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+}
+
+impl __sdk::InModule for EditorProjectResource {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `EditorProjectResource`.
+///
+/// Provides typed access to columns for query building.
+pub struct EditorProjectResourceCols {
+    pub resource_id: __sdk::__query_builder::Col<EditorProjectResource, String>,
+    pub project_id: __sdk::__query_builder::Col<EditorProjectResource, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<EditorProjectResource, String>,
+    pub asset_object_id: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub image_src: __sdk::__query_builder::Col<EditorProjectResource, String>,
+    pub object_key: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub width: __sdk::__query_builder::Col<EditorProjectResource, u32>,
+    pub height: __sdk::__query_builder::Col<EditorProjectResource, u32>,
+    pub source_type: __sdk::__query_builder::Col<EditorProjectResource, String>,
+    pub prompt: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub actual_prompt: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub model: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub provider: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub task_id: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub source_resource_id: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub created_at: __sdk::__query_builder::Col<EditorProjectResource, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<EditorProjectResource, __sdk::Timestamp>,
+    pub asset_kind: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+    pub generation_inputs_json: __sdk::__query_builder::Col<EditorProjectResource, Option<String>>,
+}
+
+impl __sdk::__query_builder::HasCols for EditorProjectResource {
+    type Cols = EditorProjectResourceCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        EditorProjectResourceCols {
+            resource_id: __sdk::__query_builder::Col::new(table_name, "resource_id"),
+            project_id: __sdk::__query_builder::Col::new(table_name, "project_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            asset_object_id: __sdk::__query_builder::Col::new(table_name, "asset_object_id"),
+            image_src: __sdk::__query_builder::Col::new(table_name, "image_src"),
+            object_key: __sdk::__query_builder::Col::new(table_name, "object_key"),
+            width: __sdk::__query_builder::Col::new(table_name, "width"),
+            height: __sdk::__query_builder::Col::new(table_name, "height"),
+            source_type: __sdk::__query_builder::Col::new(table_name, "source_type"),
+            prompt: __sdk::__query_builder::Col::new(table_name, "prompt"),
+            actual_prompt: __sdk::__query_builder::Col::new(table_name, "actual_prompt"),
+            model: __sdk::__query_builder::Col::new(table_name, "model"),
+            provider: __sdk::__query_builder::Col::new(table_name, "provider"),
+            task_id: __sdk::__query_builder::Col::new(table_name, "task_id"),
+            source_resource_id: __sdk::__query_builder::Col::new(table_name, "source_resource_id"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            asset_kind: __sdk::__query_builder::Col::new(table_name, "asset_kind"),
+            generation_inputs_json: __sdk::__query_builder::Col::new(
+                table_name,
+                "generation_inputs_json",
+            ),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `EditorProjectResource`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct EditorProjectResourceIxCols {
+    pub owner_user_id: __sdk::__query_builder::IxCol<EditorProjectResource, String>,
+    pub project_id: __sdk::__query_builder::IxCol<EditorProjectResource, String>,
+    pub resource_id: __sdk::__query_builder::IxCol<EditorProjectResource, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for EditorProjectResource {
+    type IxCols = EditorProjectResourceIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        EditorProjectResourceIxCols {
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+            project_id: __sdk::__query_builder::IxCol::new(table_name, "project_id"),
+            resource_id: __sdk::__query_builder::IxCol::new(table_name, "resource_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for EditorProjectResource {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_snapshot_type.rs
new file mode 100644
index 000000000..d0e692162
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_snapshot_type.rs
@@ -0,0 +1,24 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_canvas_snapshot_type::EditorCanvasSnapshot;
+use super::editor_project_resource_snapshot_type::EditorProjectResourceSnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectSnapshot {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub canvas: EditorCanvasSnapshot,
+    pub resources: Vec<EditorProjectResourceSnapshot>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for EditorProjectSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_table.rs
new file mode 100644
index 000000000..98c062cf2
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_table.rs
@@ -0,0 +1,159 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::editor_project_type::EditorProject;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `editor_project`.
+///
+/// Obtain a handle from the [`EditorProjectTableAccess::editor_project`] method on [`super::RemoteTables`],
+/// like `ctx.db.editor_project()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_project().on_insert(...)`.
+pub struct EditorProjectTableHandle<'ctx> {
+    imp: __sdk::TableHandle<EditorProject>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `editor_project`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait EditorProjectTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`EditorProjectTableHandle`], which mediates access to the table `editor_project`.
+    fn editor_project(&self) -> EditorProjectTableHandle<'_>;
+}
+
+impl EditorProjectTableAccess for super::RemoteTables {
+    fn editor_project(&self) -> EditorProjectTableHandle<'_> {
+        EditorProjectTableHandle {
+            imp: self.imp.get_table::<EditorProject>("editor_project"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct EditorProjectInsertCallbackId(__sdk::CallbackId);
+pub struct EditorProjectDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for EditorProjectTableHandle<'ctx> {
+    type Row = EditorProject;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = EditorProject> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = EditorProjectInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorProjectInsertCallbackId {
+        EditorProjectInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: EditorProjectInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = EditorProjectDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> EditorProjectDeleteCallbackId {
+        EditorProjectDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: EditorProjectDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct EditorProjectUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for EditorProjectTableHandle<'ctx> {
+    type UpdateCallbackId = EditorProjectUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> EditorProjectUpdateCallbackId {
+        EditorProjectUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: EditorProjectUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `project_id` unique index on the table `editor_project`,
+/// which allows point queries on the field of the same name
+/// via the [`EditorProjectProjectIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.editor_project().project_id().find(...)`.
+pub struct EditorProjectProjectIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<EditorProject, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> EditorProjectTableHandle<'ctx> {
+    /// Get a handle on the `project_id` unique index on the table `editor_project`.
+    pub fn project_id(&self) -> EditorProjectProjectIdUnique<'ctx> {
+        EditorProjectProjectIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("project_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> EditorProjectProjectIdUnique<'ctx> {
+    /// Find the subscribed row whose `project_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<EditorProject> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<EditorProject>("editor_project");
+    _table.add_unique_constraint::<String>("project_id", |row| &row.project_id);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<EditorProject>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<EditorProject>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `EditorProject`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait editor_projectQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `EditorProject`.
+    fn editor_project(&self) -> __sdk::__query_builder::Table<EditorProject>;
+}
+
+impl editor_projectQueryTableAccess for __sdk::QueryTableAccessor {
+    fn editor_project(&self) -> __sdk::__query_builder::Table<EditorProject> {
+        __sdk::__query_builder::Table::new("editor_project")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_type.rs
new file mode 100644
index 000000000..31f80b3df
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_type.rs
@@ -0,0 +1,75 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProject {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub viewport_x: f64,
+    pub viewport_y: f64,
+    pub viewport_scale: f64,
+    pub layers_json: String,
+    pub created_at: __sdk::Timestamp,
+    pub updated_at: __sdk::Timestamp,
+}
+
+impl __sdk::InModule for EditorProject {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `EditorProject`.
+///
+/// Provides typed access to columns for query building.
+pub struct EditorProjectCols {
+    pub project_id: __sdk::__query_builder::Col<EditorProject, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<EditorProject, String>,
+    pub title: __sdk::__query_builder::Col<EditorProject, String>,
+    pub viewport_x: __sdk::__query_builder::Col<EditorProject, f64>,
+    pub viewport_y: __sdk::__query_builder::Col<EditorProject, f64>,
+    pub viewport_scale: __sdk::__query_builder::Col<EditorProject, f64>,
+    pub layers_json: __sdk::__query_builder::Col<EditorProject, String>,
+    pub created_at: __sdk::__query_builder::Col<EditorProject, __sdk::Timestamp>,
+    pub updated_at: __sdk::__query_builder::Col<EditorProject, __sdk::Timestamp>,
+}
+
+impl __sdk::__query_builder::HasCols for EditorProject {
+    type Cols = EditorProjectCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        EditorProjectCols {
+            project_id: __sdk::__query_builder::Col::new(table_name, "project_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            title: __sdk::__query_builder::Col::new(table_name, "title"),
+            viewport_x: __sdk::__query_builder::Col::new(table_name, "viewport_x"),
+            viewport_y: __sdk::__query_builder::Col::new(table_name, "viewport_y"),
+            viewport_scale: __sdk::__query_builder::Col::new(table_name, "viewport_scale"),
+            layers_json: __sdk::__query_builder::Col::new(table_name, "layers_json"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `EditorProject`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct EditorProjectIxCols {
+    pub owner_user_id: __sdk::__query_builder::IxCol<EditorProject, String>,
+    pub project_id: __sdk::__query_builder::IxCol<EditorProject, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for EditorProject {
+    type IxCols = EditorProjectIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        EditorProjectIxCols {
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+            project_id: __sdk::__query_builder::IxCol::new(table_name, "project_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for EditorProject {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/editor_project_viewport_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_viewport_snapshot_type.rs
new file mode 100644
index 000000000..c4caee3f2
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/editor_project_viewport_snapshot_type.rs
@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct EditorProjectViewportSnapshot {
+    pub x: f64,
+    pub y: f64,
+    pub scale: f64,
+}
+
+impl __sdk::InModule for EditorProjectViewportSnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_authenticate_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_authenticate_input_type.rs
new file mode 100644
index 000000000..1fec84c0e
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_authenticate_input_type.rs
@@ -0,0 +1,16 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeyAuthenticateInput {
+    pub key_hash: String,
+    pub used_at_micros: i64,
+}
+
+impl __sdk::InModule for ExternalApiKeyAuthenticateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_create_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_create_input_type.rs
new file mode 100644
index 000000000..7a3081292
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_create_input_type.rs
@@ -0,0 +1,21 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeyCreateInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub key_hash: String,
+    pub scopes_json: String,
+    pub now_micros: i64,
+}
+
+impl __sdk::InModule for ExternalApiKeyCreateInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_list_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_list_input_type.rs
new file mode 100644
index 000000000..52c6cc740
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_list_input_type.rs
@@ -0,0 +1,15 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeyListInput {
+    pub owner_user_id: String,
+}
+
+impl __sdk::InModule for ExternalApiKeyListInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_procedure_result_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_procedure_result_type.rs
new file mode 100644
index 000000000..18feb9522
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_procedure_result_type.rs
@@ -0,0 +1,20 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_api_key_snapshot_type::ExternalApiKeySnapshot;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeyProcedureResult {
+    pub ok: bool,
+    pub key: Option<ExternalApiKeySnapshot>,
+    pub keys: Vec<ExternalApiKeySnapshot>,
+    pub error_message: Option<String>,
+}
+
+impl __sdk::InModule for ExternalApiKeyProcedureResult {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_revoke_input_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_revoke_input_type.rs
new file mode 100644
index 000000000..530a2acac
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_revoke_input_type.rs
@@ -0,0 +1,17 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeyRevokeInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub revoked_at_micros: i64,
+}
+
+impl __sdk::InModule for ExternalApiKeyRevokeInput {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_snapshot_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_snapshot_type.rs
new file mode 100644
index 000000000..5e9dc0c4b
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_snapshot_type.rs
@@ -0,0 +1,23 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKeySnapshot {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub scopes_json: String,
+    pub created_at_micros: i64,
+    pub last_used_at_micros: Option<i64>,
+    pub revoked_at_micros: Option<i64>,
+    pub updated_at_micros: i64,
+}
+
+impl __sdk::InModule for ExternalApiKeySnapshot {
+    type Module = super::RemoteModule;
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_table.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_table.rs
new file mode 100644
index 000000000..b07fbdfdd
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_table.rs
@@ -0,0 +1,190 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use super::external_api_key_type::ExternalApiKey;
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+/// Table handle for the table `external_api_key`.
+///
+/// Obtain a handle from the [`ExternalApiKeyTableAccess::external_api_key`] method on [`super::RemoteTables`],
+/// like `ctx.db.external_api_key()`.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.external_api_key().on_insert(...)`.
+pub struct ExternalApiKeyTableHandle<'ctx> {
+    imp: __sdk::TableHandle<ExternalApiKey>,
+    ctx: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the table `external_api_key`.
+///
+/// Implemented for [`super::RemoteTables`].
+pub trait ExternalApiKeyTableAccess {
+    #[allow(non_snake_case)]
+    /// Obtain a [`ExternalApiKeyTableHandle`], which mediates access to the table `external_api_key`.
+    fn external_api_key(&self) -> ExternalApiKeyTableHandle<'_>;
+}
+
+impl ExternalApiKeyTableAccess for super::RemoteTables {
+    fn external_api_key(&self) -> ExternalApiKeyTableHandle<'_> {
+        ExternalApiKeyTableHandle {
+            imp: self.imp.get_table::<ExternalApiKey>("external_api_key"),
+            ctx: std::marker::PhantomData,
+        }
+    }
+}
+
+pub struct ExternalApiKeyInsertCallbackId(__sdk::CallbackId);
+pub struct ExternalApiKeyDeleteCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::Table for ExternalApiKeyTableHandle<'ctx> {
+    type Row = ExternalApiKey;
+    type EventContext = super::EventContext;
+
+    fn count(&self) -> u64 {
+        self.imp.count()
+    }
+    fn iter(&self) -> impl Iterator<Item = ExternalApiKey> + '_ {
+        self.imp.iter()
+    }
+
+    type InsertCallbackId = ExternalApiKeyInsertCallbackId;
+
+    fn on_insert(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> ExternalApiKeyInsertCallbackId {
+        ExternalApiKeyInsertCallbackId(self.imp.on_insert(Box::new(callback)))
+    }
+
+    fn remove_on_insert(&self, callback: ExternalApiKeyInsertCallbackId) {
+        self.imp.remove_on_insert(callback.0)
+    }
+
+    type DeleteCallbackId = ExternalApiKeyDeleteCallbackId;
+
+    fn on_delete(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row) + Send + 'static,
+    ) -> ExternalApiKeyDeleteCallbackId {
+        ExternalApiKeyDeleteCallbackId(self.imp.on_delete(Box::new(callback)))
+    }
+
+    fn remove_on_delete(&self, callback: ExternalApiKeyDeleteCallbackId) {
+        self.imp.remove_on_delete(callback.0)
+    }
+}
+
+pub struct ExternalApiKeyUpdateCallbackId(__sdk::CallbackId);
+
+impl<'ctx> __sdk::TableWithPrimaryKey for ExternalApiKeyTableHandle<'ctx> {
+    type UpdateCallbackId = ExternalApiKeyUpdateCallbackId;
+
+    fn on_update(
+        &self,
+        callback: impl FnMut(&Self::EventContext, &Self::Row, &Self::Row) + Send + 'static,
+    ) -> ExternalApiKeyUpdateCallbackId {
+        ExternalApiKeyUpdateCallbackId(self.imp.on_update(Box::new(callback)))
+    }
+
+    fn remove_on_update(&self, callback: ExternalApiKeyUpdateCallbackId) {
+        self.imp.remove_on_update(callback.0)
+    }
+}
+
+/// Access to the `key_id` unique index on the table `external_api_key`,
+/// which allows point queries on the field of the same name
+/// via the [`ExternalApiKeyKeyIdUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.external_api_key().key_id().find(...)`.
+pub struct ExternalApiKeyKeyIdUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<ExternalApiKey, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> ExternalApiKeyTableHandle<'ctx> {
+    /// Get a handle on the `key_id` unique index on the table `external_api_key`.
+    pub fn key_id(&self) -> ExternalApiKeyKeyIdUnique<'ctx> {
+        ExternalApiKeyKeyIdUnique {
+            imp: self.imp.get_unique_constraint::<String>("key_id"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> ExternalApiKeyKeyIdUnique<'ctx> {
+    /// Find the subscribed row whose `key_id` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<ExternalApiKey> {
+        self.imp.find(col_val)
+    }
+}
+
+/// Access to the `key_hash` unique index on the table `external_api_key`,
+/// which allows point queries on the field of the same name
+/// via the [`ExternalApiKeyKeyHashUnique::find`] method.
+///
+/// Users are encouraged not to explicitly reference this type,
+/// but to directly chain method calls,
+/// like `ctx.db.external_api_key().key_hash().find(...)`.
+pub struct ExternalApiKeyKeyHashUnique<'ctx> {
+    imp: __sdk::UniqueConstraintHandle<ExternalApiKey, String>,
+    phantom: std::marker::PhantomData<&'ctx super::RemoteTables>,
+}
+
+impl<'ctx> ExternalApiKeyTableHandle<'ctx> {
+    /// Get a handle on the `key_hash` unique index on the table `external_api_key`.
+    pub fn key_hash(&self) -> ExternalApiKeyKeyHashUnique<'ctx> {
+        ExternalApiKeyKeyHashUnique {
+            imp: self.imp.get_unique_constraint::<String>("key_hash"),
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<'ctx> ExternalApiKeyKeyHashUnique<'ctx> {
+    /// Find the subscribed row whose `key_hash` column value is equal to `col_val`,
+    /// if such a row is present in the client cache.
+    pub fn find(&self, col_val: &String) -> Option<ExternalApiKey> {
+        self.imp.find(col_val)
+    }
+}
+
+#[doc(hidden)]
+pub(super) fn register_table(client_cache: &mut __sdk::ClientCache<super::RemoteModule>) {
+    let _table = client_cache.get_or_make_table::<ExternalApiKey>("external_api_key");
+    _table.add_unique_constraint::<String>("key_id", |row| &row.key_id);
+    _table.add_unique_constraint::<String>("key_hash", |row| &row.key_hash);
+}
+
+#[doc(hidden)]
+pub(super) fn parse_table_update(
+    raw_updates: __ws::v2::TableUpdate,
+) -> __sdk::Result<__sdk::TableUpdate<ExternalApiKey>> {
+    __sdk::TableUpdate::parse_table_update(raw_updates).map_err(|e| {
+        __sdk::InternalError::failed_parse("TableUpdate<ExternalApiKey>", "TableUpdate")
+            .with_cause(e)
+            .into()
+    })
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for query builder access to the table `ExternalApiKey`.
+///
+/// Implemented for [`__sdk::QueryTableAccessor`].
+pub trait external_api_keyQueryTableAccess {
+    #[allow(non_snake_case)]
+    /// Get a query builder for the table `ExternalApiKey`.
+    fn external_api_key(&self) -> __sdk::__query_builder::Table<ExternalApiKey>;
+}
+
+impl external_api_keyQueryTableAccess for __sdk::QueryTableAccessor {
+    fn external_api_key(&self) -> __sdk::__query_builder::Table<ExternalApiKey> {
+        __sdk::__query_builder::Table::new("external_api_key")
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_type.rs b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_type.rs
new file mode 100644
index 000000000..b0064ea90
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/external_api_key_type.rs
@@ -0,0 +1,80 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+pub struct ExternalApiKey {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub key_hash: String,
+    pub scopes_json: String,
+    pub created_at: __sdk::Timestamp,
+    pub last_used_at: Option<__sdk::Timestamp>,
+    pub revoked_at: Option<__sdk::Timestamp>,
+    pub updated_at: __sdk::Timestamp,
+}
+
+impl __sdk::InModule for ExternalApiKey {
+    type Module = super::RemoteModule;
+}
+
+/// Column accessor struct for the table `ExternalApiKey`.
+///
+/// Provides typed access to columns for query building.
+pub struct ExternalApiKeyCols {
+    pub key_id: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub owner_user_id: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub name: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub key_prefix: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub key_hash: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub scopes_json: __sdk::__query_builder::Col<ExternalApiKey, String>,
+    pub created_at: __sdk::__query_builder::Col<ExternalApiKey, __sdk::Timestamp>,
+    pub last_used_at: __sdk::__query_builder::Col<ExternalApiKey, Option<__sdk::Timestamp>>,
+    pub revoked_at: __sdk::__query_builder::Col<ExternalApiKey, Option<__sdk::Timestamp>>,
+    pub updated_at: __sdk::__query_builder::Col<ExternalApiKey, __sdk::Timestamp>,
+}
+
+impl __sdk::__query_builder::HasCols for ExternalApiKey {
+    type Cols = ExternalApiKeyCols;
+    fn cols(table_name: &'static str) -> Self::Cols {
+        ExternalApiKeyCols {
+            key_id: __sdk::__query_builder::Col::new(table_name, "key_id"),
+            owner_user_id: __sdk::__query_builder::Col::new(table_name, "owner_user_id"),
+            name: __sdk::__query_builder::Col::new(table_name, "name"),
+            key_prefix: __sdk::__query_builder::Col::new(table_name, "key_prefix"),
+            key_hash: __sdk::__query_builder::Col::new(table_name, "key_hash"),
+            scopes_json: __sdk::__query_builder::Col::new(table_name, "scopes_json"),
+            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
+            last_used_at: __sdk::__query_builder::Col::new(table_name, "last_used_at"),
+            revoked_at: __sdk::__query_builder::Col::new(table_name, "revoked_at"),
+            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+        }
+    }
+}
+
+/// Indexed column accessor struct for the table `ExternalApiKey`.
+///
+/// Provides typed access to indexed columns for query building.
+pub struct ExternalApiKeyIxCols {
+    pub key_hash: __sdk::__query_builder::IxCol<ExternalApiKey, String>,
+    pub key_id: __sdk::__query_builder::IxCol<ExternalApiKey, String>,
+    pub owner_user_id: __sdk::__query_builder::IxCol<ExternalApiKey, String>,
+}
+
+impl __sdk::__query_builder::HasIxCols for ExternalApiKey {
+    type IxCols = ExternalApiKeyIxCols;
+    fn ix_cols(table_name: &'static str) -> Self::IxCols {
+        ExternalApiKeyIxCols {
+            key_hash: __sdk::__query_builder::IxCol::new(table_name, "key_hash"),
+            key_id: __sdk::__query_builder::IxCol::new(table_name, "key_id"),
+            owner_user_id: __sdk::__query_builder::IxCol::new(table_name, "owner_user_id"),
+        }
+    }
+}
+
+impl __sdk::__query_builder::CanBeLookupTable for ExternalApiKey {}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_editor_asset_library_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_editor_asset_library_and_return_procedure.rs
new file mode 100644
index 000000000..dca803bbf
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_editor_asset_library_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_library_get_input_type::EditorAssetLibraryGetInput;
+use super::editor_asset_library_procedure_result_type::EditorAssetLibraryProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetEditorAssetLibraryAndReturnArgs {
+    pub input: EditorAssetLibraryGetInput,
+}
+
+impl __sdk::InModule for GetEditorAssetLibraryAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_editor_asset_library_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_editor_asset_library_and_return {
+    fn get_editor_asset_library_and_return(&self, input: EditorAssetLibraryGetInput) {
+        self.get_editor_asset_library_and_return_then(input, |_, _| {});
+    }
+
+    fn get_editor_asset_library_and_return_then(
+        &self,
+        input: EditorAssetLibraryGetInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetLibraryProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_editor_asset_library_and_return for super::RemoteProcedures {
+    fn get_editor_asset_library_and_return_then(
+        &self,
+        input: EditorAssetLibraryGetInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetLibraryProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetLibraryProcedureResult>(
+                "get_editor_asset_library_and_return",
+                GetEditorAssetLibraryAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_editor_project_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_editor_project_and_return_procedure.rs
new file mode 100644
index 000000000..07d5c4fe1
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_editor_project_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_get_input_type::EditorProjectGetInput;
+use super::editor_project_procedure_result_type::EditorProjectProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetEditorProjectAndReturnArgs {
+    pub input: EditorProjectGetInput,
+}
+
+impl __sdk::InModule for GetEditorProjectAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_editor_project_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_editor_project_and_return {
+    fn get_editor_project_and_return(&self, input: EditorProjectGetInput) {
+        self.get_editor_project_and_return_then(input, |_, _| {});
+    }
+
+    fn get_editor_project_and_return_then(
+        &self,
+        input: EditorProjectGetInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_editor_project_and_return for super::RemoteProcedures {
+    fn get_editor_project_and_return_then(
+        &self,
+        input: EditorProjectGetInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectProcedureResult>(
+                "get_editor_project_and_return",
+                GetEditorProjectAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/get_recent_editor_project_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/get_recent_editor_project_and_return_procedure.rs
new file mode 100644
index 000000000..b16395853
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/get_recent_editor_project_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_get_recent_input_type::EditorProjectGetRecentInput;
+use super::editor_project_procedure_result_type::EditorProjectProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct GetRecentEditorProjectAndReturnArgs {
+    pub input: EditorProjectGetRecentInput,
+}
+
+impl __sdk::InModule for GetRecentEditorProjectAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `get_recent_editor_project_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait get_recent_editor_project_and_return {
+    fn get_recent_editor_project_and_return(&self, input: EditorProjectGetRecentInput) {
+        self.get_recent_editor_project_and_return_then(input, |_, _| {});
+    }
+
+    fn get_recent_editor_project_and_return_then(
+        &self,
+        input: EditorProjectGetRecentInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl get_recent_editor_project_and_return for super::RemoteProcedures {
+    fn get_recent_editor_project_and_return_then(
+        &self,
+        input: EditorProjectGetRecentInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectProcedureResult>(
+                "get_recent_editor_project_and_return",
+                GetRecentEditorProjectAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_editor_projects_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_editor_projects_and_return_procedure.rs
new file mode 100644
index 000000000..fca9595d0
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_editor_projects_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_list_input_type::EditorProjectListInput;
+use super::editor_project_list_procedure_result_type::EditorProjectListProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListEditorProjectsAndReturnArgs {
+    pub input: EditorProjectListInput,
+}
+
+impl __sdk::InModule for ListEditorProjectsAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_editor_projects_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_editor_projects_and_return {
+    fn list_editor_projects_and_return(&self, input: EditorProjectListInput) {
+        self.list_editor_projects_and_return_then(input, |_, _| {});
+    }
+
+    fn list_editor_projects_and_return_then(
+        &self,
+        input: EditorProjectListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_editor_projects_and_return for super::RemoteProcedures {
+    fn list_editor_projects_and_return_then(
+        &self,
+        input: EditorProjectListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectListProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectListProcedureResult>(
+                "list_editor_projects_and_return",
+                ListEditorProjectsAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/list_external_api_keys_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/list_external_api_keys_and_return_procedure.rs
new file mode 100644
index 000000000..ca827a562
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/list_external_api_keys_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_api_key_list_input_type::ExternalApiKeyListInput;
+use super::external_api_key_procedure_result_type::ExternalApiKeyProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct ListExternalApiKeysAndReturnArgs {
+    pub input: ExternalApiKeyListInput,
+}
+
+impl __sdk::InModule for ListExternalApiKeysAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `list_external_api_keys_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait list_external_api_keys_and_return {
+    fn list_external_api_keys_and_return(&self, input: ExternalApiKeyListInput) {
+        self.list_external_api_keys_and_return_then(input, |_, _| {});
+    }
+
+    fn list_external_api_keys_and_return_then(
+        &self,
+        input: ExternalApiKeyListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl list_external_api_keys_and_return for super::RemoteProcedures {
+    fn list_external_api_keys_and_return_then(
+        &self,
+        input: ExternalApiKeyListInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalApiKeyProcedureResult>(
+                "list_external_api_keys_and_return",
+                ListExternalApiKeysAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/rename_editor_project_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/rename_editor_project_and_return_procedure.rs
new file mode 100644
index 000000000..408122981
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/rename_editor_project_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_procedure_result_type::EditorProjectProcedureResult;
+use super::editor_project_rename_input_type::EditorProjectRenameInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct RenameEditorProjectAndReturnArgs {
+    pub input: EditorProjectRenameInput,
+}
+
+impl __sdk::InModule for RenameEditorProjectAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `rename_editor_project_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait rename_editor_project_and_return {
+    fn rename_editor_project_and_return(&self, input: EditorProjectRenameInput) {
+        self.rename_editor_project_and_return_then(input, |_, _| {});
+    }
+
+    fn rename_editor_project_and_return_then(
+        &self,
+        input: EditorProjectRenameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl rename_editor_project_and_return for super::RemoteProcedures {
+    fn rename_editor_project_and_return_then(
+        &self,
+        input: EditorProjectRenameInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectProcedureResult>(
+                "rename_editor_project_and_return",
+                RenameEditorProjectAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/revoke_external_api_key_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/revoke_external_api_key_and_return_procedure.rs
new file mode 100644
index 000000000..d893b2180
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/revoke_external_api_key_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::external_api_key_procedure_result_type::ExternalApiKeyProcedureResult;
+use super::external_api_key_revoke_input_type::ExternalApiKeyRevokeInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct RevokeExternalApiKeyAndReturnArgs {
+    pub input: ExternalApiKeyRevokeInput,
+}
+
+impl __sdk::InModule for RevokeExternalApiKeyAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `revoke_external_api_key_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait revoke_external_api_key_and_return {
+    fn revoke_external_api_key_and_return(&self, input: ExternalApiKeyRevokeInput) {
+        self.revoke_external_api_key_and_return_then(input, |_, _| {});
+    }
+
+    fn revoke_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyRevokeInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl revoke_external_api_key_and_return for super::RemoteProcedures {
+    fn revoke_external_api_key_and_return_then(
+        &self,
+        input: ExternalApiKeyRevokeInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<ExternalApiKeyProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, ExternalApiKeyProcedureResult>(
+                "revoke_external_api_key_and_return",
+                RevokeExternalApiKeyAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/save_editor_project_layout_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/save_editor_project_layout_and_return_procedure.rs
new file mode 100644
index 000000000..17585bdf2
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/save_editor_project_layout_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_project_layout_save_input_type::EditorProjectLayoutSaveInput;
+use super::editor_project_procedure_result_type::EditorProjectProcedureResult;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct SaveEditorProjectLayoutAndReturnArgs {
+    pub input: EditorProjectLayoutSaveInput,
+}
+
+impl __sdk::InModule for SaveEditorProjectLayoutAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `save_editor_project_layout_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait save_editor_project_layout_and_return {
+    fn save_editor_project_layout_and_return(&self, input: EditorProjectLayoutSaveInput) {
+        self.save_editor_project_layout_and_return_then(input, |_, _| {});
+    }
+
+    fn save_editor_project_layout_and_return_then(
+        &self,
+        input: EditorProjectLayoutSaveInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl save_editor_project_layout_and_return for super::RemoteProcedures {
+    fn save_editor_project_layout_and_return_then(
+        &self,
+        input: EditorProjectLayoutSaveInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorProjectProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorProjectProcedureResult>(
+                "save_editor_project_layout_and_return",
+                SaveEditorProjectLayoutAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_and_return_procedure.rs
new file mode 100644
index 000000000..1ec662919
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_procedure_result_type::EditorAssetProcedureResult;
+use super::editor_asset_update_input_type::EditorAssetUpdateInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct UpdateEditorAssetAndReturnArgs {
+    pub input: EditorAssetUpdateInput,
+}
+
+impl __sdk::InModule for UpdateEditorAssetAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `update_editor_asset_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait update_editor_asset_and_return {
+    fn update_editor_asset_and_return(&self, input: EditorAssetUpdateInput) {
+        self.update_editor_asset_and_return_then(input, |_, _| {});
+    }
+
+    fn update_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl update_editor_asset_and_return for super::RemoteProcedures {
+    fn update_editor_asset_and_return_then(
+        &self,
+        input: EditorAssetUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetProcedureResult>(
+                "update_editor_asset_and_return",
+                UpdateEditorAssetAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_folder_and_return_procedure.rs b/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_folder_and_return_procedure.rs
new file mode 100644
index 000000000..a5ec71437
--- /dev/null
+++ b/server-rs/crates/spacetime-client/src/module_bindings/update_editor_asset_folder_and_return_procedure.rs
@@ -0,0 +1,59 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+#![allow(unused, clippy::all)]
+use spacetimedb_sdk::__codegen::{self as __sdk, __lib, __sats, __ws};
+
+use super::editor_asset_folder_procedure_result_type::EditorAssetFolderProcedureResult;
+use super::editor_asset_folder_update_input_type::EditorAssetFolderUpdateInput;
+
+#[derive(__lib::ser::Serialize, __lib::de::Deserialize, Clone, PartialEq, Debug)]
+#[sats(crate = __lib)]
+struct UpdateEditorAssetFolderAndReturnArgs {
+    pub input: EditorAssetFolderUpdateInput,
+}
+
+impl __sdk::InModule for UpdateEditorAssetFolderAndReturnArgs {
+    type Module = super::RemoteModule;
+}
+
+#[allow(non_camel_case_types)]
+/// Extension trait for access to the procedure `update_editor_asset_folder_and_return`.
+///
+/// Implemented for [`super::RemoteProcedures`].
+pub trait update_editor_asset_folder_and_return {
+    fn update_editor_asset_folder_and_return(&self, input: EditorAssetFolderUpdateInput) {
+        self.update_editor_asset_folder_and_return_then(input, |_, _| {});
+    }
+
+    fn update_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    );
+}
+
+impl update_editor_asset_folder_and_return for super::RemoteProcedures {
+    fn update_editor_asset_folder_and_return_then(
+        &self,
+        input: EditorAssetFolderUpdateInput,
+
+        __callback: impl FnOnce(
+                &super::ProcedureEventContext,
+                Result<EditorAssetFolderProcedureResult, __sdk::InternalError>,
+            ) + Send
+            + 'static,
+    ) {
+        self.imp
+            .invoke_procedure_with_callback::<_, EditorAssetFolderProcedureResult>(
+                "update_editor_asset_folder_and_return",
+                UpdateEditorAssetFolderAndReturnArgs { input },
+                __callback,
+            );
+    }
+}
diff --git a/server-rs/crates/spacetime-module/src/editor_project_storage.rs b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
new file mode 100644
index 000000000..0195c9da9
--- /dev/null
+++ b/server-rs/crates/spacetime-module/src/editor_project_storage.rs
@@ -0,0 +1,1596 @@
+use crate::*;
+
+const EDITOR_PROJECT_DEFAULT_TITLE: &str = "未命名画布";
+const EDITOR_CANVAS_DEFAULT_TITLE: &str = "默认画布";
+const EDITOR_ASSET_DEFAULT_FOLDER_ID: &str = "project";
+const EDITOR_ASSET_DEFAULT_FOLDER_LABEL: &str = "项目素材";
+const EDITOR_PROJECT_MAX_TITLE_CHARS: usize = 80;
+const EDITOR_ASSET_MAX_LABEL_CHARS: usize = 80;
+const EDITOR_PROJECT_MAX_LAYOUT_JSON_BYTES: usize = 256 * 1024;
+const EDITOR_PROJECT_SOURCE_TYPES: [&str; 3] = ["uploaded", "generated", "mock_generated"];
+
+#[spacetimedb::table(
+    accessor = editor_project,
+    index(accessor = by_editor_project_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct EditorProject {
+    #[primary_key]
+    project_id: String,
+    owner_user_id: String,
+    title: String,
+    viewport_x: f64,
+    viewport_y: f64,
+    viewport_scale: f64,
+    layers_json: String,
+    created_at: Timestamp,
+    updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = editor_canvas,
+    index(accessor = by_editor_canvas_project_id, btree(columns = [project_id])),
+    index(accessor = by_editor_canvas_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct EditorCanvas {
+    #[primary_key]
+    canvas_id: String,
+    project_id: String,
+    owner_user_id: String,
+    title: String,
+    viewport_x: f64,
+    viewport_y: f64,
+    viewport_scale: f64,
+    layers_json: String,
+    created_at: Timestamp,
+    updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = editor_project_resource,
+    index(accessor = by_editor_project_resource_project_id, btree(columns = [project_id])),
+    index(accessor = by_editor_project_resource_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct EditorProjectResource {
+    #[primary_key]
+    resource_id: String,
+    project_id: String,
+    owner_user_id: String,
+    asset_object_id: Option<String>,
+    image_src: String,
+    object_key: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    source_resource_id: Option<String>,
+    created_at: Timestamp,
+    updated_at: Timestamp,
+    #[default(None::<String>)]
+    asset_kind: Option<String>,
+    #[default(None::<String>)]
+    generation_inputs_json: Option<String>,
+}
+
+#[spacetimedb::table(
+    accessor = editor_asset_folder,
+    index(accessor = by_editor_asset_folder_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct EditorAssetFolder {
+    #[primary_key]
+    folder_id: String,
+    owner_user_id: String,
+    label: String,
+    sort_order: u32,
+    collapsed: bool,
+    system_default: bool,
+    created_at: Timestamp,
+    updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = editor_asset,
+    index(accessor = by_editor_asset_owner_user_id, btree(columns = [owner_user_id])),
+    index(accessor = by_editor_asset_folder_id, btree(columns = [folder_id]))
+)]
+pub struct EditorAsset {
+    #[primary_key]
+    asset_id: String,
+    owner_user_id: String,
+    folder_id: String,
+    label: String,
+    asset_object_id: Option<String>,
+    image_src: String,
+    object_key: Option<String>,
+    width: u32,
+    height: u32,
+    source_type: String,
+    prompt: Option<String>,
+    actual_prompt: Option<String>,
+    model: Option<String>,
+    provider: Option<String>,
+    task_id: Option<String>,
+    created_at: Timestamp,
+    updated_at: Timestamp,
+    #[default(None::<String>)]
+    asset_kind: Option<String>,
+    #[default(None::<String>)]
+    generation_inputs_json: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectViewportSnapshot {
+    pub x: f64,
+    pub y: f64,
+    pub scale: f64,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectCreateInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectGetInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectGetRecentInput {
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectListInput {
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectRenameInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectDeleteInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectLayoutSaveInput {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub viewport: EditorProjectViewportSnapshot,
+    pub layers_json: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectResourceCreateInput {
+    pub resource_id: String,
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectResourceSnapshot {
+    pub resource_id: String,
+    pub project_id: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub source_resource_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetFolderSnapshot {
+    pub folder_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub collapsed: bool,
+    pub system_default: bool,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetSnapshot {
+    pub asset_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetLibrarySnapshot {
+    pub folders: Vec<EditorAssetFolderSnapshot>,
+    pub assets: Vec<EditorAssetSnapshot>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetLibraryGetInput {
+    pub owner_user_id: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetFolderCreateInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: String,
+    pub sort_order: u32,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetFolderUpdateInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub collapsed: Option<bool>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetFolderDeleteInput {
+    pub folder_id: String,
+    pub owner_user_id: String,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetCreateInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub folder_id: String,
+    pub label: String,
+    pub asset_object_id: Option<String>,
+    pub image_src: String,
+    pub object_key: Option<String>,
+    pub width: u32,
+    pub height: u32,
+    pub source_type: String,
+    pub prompt: Option<String>,
+    pub actual_prompt: Option<String>,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub task_id: Option<String>,
+    pub asset_kind: Option<String>,
+    pub generation_inputs_json: Option<String>,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetUpdateInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+    pub label: Option<String>,
+    pub folder_id: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetDeleteInput {
+    pub asset_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorCanvasSnapshot {
+    pub canvas_id: String,
+    pub project_id: String,
+    pub title: String,
+    pub viewport: EditorProjectViewportSnapshot,
+    pub layers_json: String,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectSnapshot {
+    pub project_id: String,
+    pub owner_user_id: String,
+    pub title: String,
+    pub canvas: EditorCanvasSnapshot,
+    pub resources: Vec<EditorProjectResourceSnapshot>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectProcedureResult {
+    pub ok: bool,
+    pub project: Option<EditorProjectSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectListProcedureResult {
+    pub ok: bool,
+    pub projects: Vec<EditorProjectSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorProjectDeleteProcedureResult {
+    pub ok: bool,
+    pub deleted_project_id: Option<String>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct EditorProjectResourceProcedureResult {
+    pub ok: bool,
+    pub resource: Option<EditorProjectResourceSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetLibraryProcedureResult {
+    pub ok: bool,
+    pub library: Option<EditorAssetLibrarySnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetFolderProcedureResult {
+    pub ok: bool,
+    pub folder: Option<EditorAssetFolderSnapshot>,
+    pub library: Option<EditorAssetLibrarySnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct EditorAssetProcedureResult {
+    pub ok: bool,
+    pub asset: Option<EditorAssetSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[spacetimedb::procedure]
+pub fn create_editor_project_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectCreateInput,
+) -> EditorProjectProcedureResult {
+    match ctx.try_with_tx(|tx| create_editor_project(tx, input.clone())) {
+        Ok(project) => editor_project_ok(Some(project)),
+        Err(message) => editor_project_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn get_recent_editor_project_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectGetRecentInput,
+) -> EditorProjectProcedureResult {
+    match ctx.try_with_tx(|tx| get_recent_editor_project(tx, input.clone())) {
+        Ok(project) => editor_project_ok(project),
+        Err(message) => editor_project_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn list_editor_projects_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectListInput,
+) -> EditorProjectListProcedureResult {
+    match ctx.try_with_tx(|tx| list_editor_projects(tx, input.clone())) {
+        Ok(projects) => EditorProjectListProcedureResult {
+            ok: true,
+            projects,
+            error_message: None,
+        },
+        Err(message) => EditorProjectListProcedureResult {
+            ok: false,
+            projects: Vec::new(),
+            error_message: Some(message),
+        },
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn get_editor_project_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectGetInput,
+) -> EditorProjectProcedureResult {
+    match ctx.try_with_tx(|tx| get_editor_project(tx, input.clone())) {
+        Ok(project) => editor_project_ok(Some(project)),
+        Err(message) => editor_project_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn save_editor_project_layout_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectLayoutSaveInput,
+) -> EditorProjectProcedureResult {
+    match ctx.try_with_tx(|tx| save_editor_project_layout(tx, input.clone())) {
+        Ok(project) => editor_project_ok(Some(project)),
+        Err(message) => editor_project_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn rename_editor_project_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectRenameInput,
+) -> EditorProjectProcedureResult {
+    match ctx.try_with_tx(|tx| rename_editor_project(tx, input.clone())) {
+        Ok(project) => editor_project_ok(Some(project)),
+        Err(message) => editor_project_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn delete_editor_project_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectDeleteInput,
+) -> EditorProjectDeleteProcedureResult {
+    match ctx.try_with_tx(|tx| delete_editor_project(tx, input.clone())) {
+        Ok(project_id) => EditorProjectDeleteProcedureResult {
+            ok: true,
+            deleted_project_id: Some(project_id),
+            error_message: None,
+        },
+        Err(message) => EditorProjectDeleteProcedureResult {
+            ok: false,
+            deleted_project_id: None,
+            error_message: Some(message),
+        },
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn create_editor_project_resource_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorProjectResourceCreateInput,
+) -> EditorProjectResourceProcedureResult {
+    match ctx.try_with_tx(|tx| create_editor_project_resource(tx, input.clone())) {
+        Ok(resource) => EditorProjectResourceProcedureResult {
+            ok: true,
+            resource: Some(resource),
+            error_message: None,
+        },
+        Err(message) => EditorProjectResourceProcedureResult {
+            ok: false,
+            resource: None,
+            error_message: Some(message),
+        },
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn get_editor_asset_library_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetLibraryGetInput,
+) -> EditorAssetLibraryProcedureResult {
+    match ctx.try_with_tx(|tx| get_editor_asset_library(tx, input.clone())) {
+        Ok(library) => editor_asset_library_ok(library),
+        Err(message) => editor_asset_library_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn create_editor_asset_folder_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetFolderCreateInput,
+) -> EditorAssetFolderProcedureResult {
+    match ctx.try_with_tx(|tx| create_editor_asset_folder(tx, input.clone())) {
+        Ok(folder) => editor_asset_folder_ok(Some(folder), None),
+        Err(message) => editor_asset_folder_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn update_editor_asset_folder_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetFolderUpdateInput,
+) -> EditorAssetFolderProcedureResult {
+    match ctx.try_with_tx(|tx| update_editor_asset_folder(tx, input.clone())) {
+        Ok(folder) => editor_asset_folder_ok(Some(folder), None),
+        Err(message) => editor_asset_folder_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn delete_editor_asset_folder_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetFolderDeleteInput,
+) -> EditorAssetFolderProcedureResult {
+    match ctx.try_with_tx(|tx| delete_editor_asset_folder(tx, input.clone())) {
+        Ok(library) => editor_asset_folder_ok(None, Some(library)),
+        Err(message) => editor_asset_folder_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn create_editor_asset_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetCreateInput,
+) -> EditorAssetProcedureResult {
+    match ctx.try_with_tx(|tx| create_editor_asset(tx, input.clone())) {
+        Ok(asset) => editor_asset_ok(Some(asset)),
+        Err(message) => editor_asset_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn update_editor_asset_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetUpdateInput,
+) -> EditorAssetProcedureResult {
+    match ctx.try_with_tx(|tx| update_editor_asset(tx, input.clone())) {
+        Ok(asset) => editor_asset_ok(Some(asset)),
+        Err(message) => editor_asset_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn delete_editor_asset_and_return(
+    ctx: &mut ProcedureContext,
+    input: EditorAssetDeleteInput,
+) -> EditorAssetProcedureResult {
+    match ctx.try_with_tx(|tx| delete_editor_asset(tx, input.clone())) {
+        Ok(asset) => editor_asset_ok(Some(asset)),
+        Err(message) => editor_asset_error(message),
+    }
+}
+
+fn create_editor_project(
+    ctx: &ReducerContext,
+    input: EditorProjectCreateInput,
+) -> Result<EditorProjectSnapshot, String> {
+    let project_id = normalize_required(&input.project_id, "editor_project.project_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let title = normalize_title(&input.title);
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+
+    if ctx
+        .db
+        .editor_project()
+        .project_id()
+        .find(&project_id)
+        .is_some()
+    {
+        return Err("图片画布工程已存在".to_string());
+    }
+
+    ctx.db.editor_project().insert(EditorProject {
+        project_id: project_id.clone(),
+        owner_user_id: owner_user_id.clone(),
+        title,
+        viewport_x: 0.0,
+        viewport_y: 0.0,
+        viewport_scale: 1.0,
+        layers_json: "[]".to_string(),
+        created_at: now,
+        updated_at: now,
+    });
+    ensure_default_canvas(ctx, project_id.as_str(), owner_user_id.as_str(), None, now)?;
+
+    build_project_snapshot(ctx, project_id.as_str())
+}
+
+fn get_recent_editor_project(
+    ctx: &ReducerContext,
+    input: EditorProjectGetRecentInput,
+) -> Result<Option<EditorProjectSnapshot>, String> {
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let mut projects = ctx
+        .db
+        .editor_project()
+        .by_editor_project_owner_user_id()
+        .filter(&owner_user_id)
+        .collect::<Vec<_>>();
+
+    projects.sort_by(|left, right| {
+        right
+            .updated_at
+            .to_micros_since_unix_epoch()
+            .cmp(&left.updated_at.to_micros_since_unix_epoch())
+            .then_with(|| right.project_id.cmp(&left.project_id))
+    });
+
+    projects
+        .first()
+        .map(|project| build_project_snapshot(ctx, project.project_id.as_str()))
+        .transpose()
+}
+
+fn list_editor_projects(
+    ctx: &ReducerContext,
+    input: EditorProjectListInput,
+) -> Result<Vec<EditorProjectSnapshot>, String> {
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let mut projects = ctx
+        .db
+        .editor_project()
+        .by_editor_project_owner_user_id()
+        .filter(&owner_user_id)
+        .collect::<Vec<_>>();
+
+    projects.sort_by(|left, right| {
+        right
+            .updated_at
+            .to_micros_since_unix_epoch()
+            .cmp(&left.updated_at.to_micros_since_unix_epoch())
+            .then_with(|| right.project_id.cmp(&left.project_id))
+    });
+
+    projects
+        .into_iter()
+        .map(|project| build_project_snapshot(ctx, project.project_id.as_str()))
+        .collect()
+}
+
+fn get_editor_project(
+    ctx: &ReducerContext,
+    input: EditorProjectGetInput,
+) -> Result<EditorProjectSnapshot, String> {
+    let project_id = normalize_required(&input.project_id, "editor_project.project_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let project = require_owned_project(ctx, project_id.as_str(), owner_user_id.as_str())?;
+    build_project_snapshot(ctx, project.project_id.as_str())
+}
+
+fn rename_editor_project(
+    ctx: &ReducerContext,
+    input: EditorProjectRenameInput,
+) -> Result<EditorProjectSnapshot, String> {
+    let project_id = normalize_required(&input.project_id, "editor_project.project_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let project = require_owned_project(ctx, project_id.as_str(), owner_user_id.as_str())?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+
+    ctx.db.editor_project().project_id().delete(&project_id);
+    ctx.db.editor_project().insert(EditorProject {
+        project_id: project.project_id.clone(),
+        owner_user_id: project.owner_user_id,
+        title: normalize_title(&input.title),
+        viewport_x: project.viewport_x,
+        viewport_y: project.viewport_y,
+        viewport_scale: project.viewport_scale,
+        layers_json: project.layers_json,
+        created_at: project.created_at,
+        updated_at: now,
+    });
+
+    build_project_snapshot(ctx, project_id.as_str())
+}
+
+fn delete_editor_project(
+    ctx: &ReducerContext,
+    input: EditorProjectDeleteInput,
+) -> Result<String, String> {
+    let project_id = normalize_required(&input.project_id, "editor_project.project_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    require_owned_project(ctx, project_id.as_str(), owner_user_id.as_str())?;
+    let project_key = project_id.clone();
+    let canvas_ids = ctx
+        .db
+        .editor_canvas()
+        .by_editor_canvas_project_id()
+        .filter(&project_key)
+        .map(|canvas| canvas.canvas_id)
+        .collect::<Vec<_>>();
+    let resource_ids = ctx
+        .db
+        .editor_project_resource()
+        .by_editor_project_resource_project_id()
+        .filter(&project_key)
+        .map(|resource| resource.resource_id)
+        .collect::<Vec<_>>();
+
+    for canvas_id in canvas_ids {
+        ctx.db.editor_canvas().canvas_id().delete(&canvas_id);
+    }
+    for resource_id in resource_ids {
+        ctx.db
+            .editor_project_resource()
+            .resource_id()
+            .delete(&resource_id);
+    }
+    ctx.db.editor_project().project_id().delete(&project_id);
+
+    Ok(project_id)
+}
+
+fn save_editor_project_layout(
+    ctx: &ReducerContext,
+    input: EditorProjectLayoutSaveInput,
+) -> Result<EditorProjectSnapshot, String> {
+    let project_id = normalize_required(&input.project_id, "editor_project.project_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_project.owner_user_id")?;
+    let input_layers_json = normalize_layout_json(input.layers_json)?;
+    let project = require_owned_project(ctx, project_id.as_str(), owner_user_id.as_str())?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    let canvas = ensure_default_canvas(
+        ctx,
+        project.project_id.as_str(),
+        project.owner_user_id.as_str(),
+        Some(&project),
+        now,
+    )?;
+    let _ = migrate_canvas_layer_asset_metadata(
+        ctx,
+        project.project_id.as_str(),
+        owner_user_id.as_str(),
+        canvas.layers_json.clone(),
+        now,
+    )?;
+    let layers_json = migrate_canvas_layer_asset_metadata(
+        ctx,
+        project.project_id.as_str(),
+        owner_user_id.as_str(),
+        input_layers_json,
+        now,
+    )?;
+
+    ctx.db.editor_canvas().canvas_id().delete(&canvas.canvas_id);
+    ctx.db.editor_canvas().insert(EditorCanvas {
+        canvas_id: canvas.canvas_id,
+        project_id: project.project_id.clone(),
+        owner_user_id: project.owner_user_id.clone(),
+        title: canvas.title,
+        viewport_x: input.viewport.x,
+        viewport_y: input.viewport.y,
+        viewport_scale: input.viewport.scale.clamp(0.01, 8.0),
+        layers_json: layers_json.clone(),
+        created_at: canvas.created_at,
+        updated_at: now,
+    });
+    ctx.db.editor_project().project_id().delete(&project_id);
+    ctx.db.editor_project().insert(EditorProject {
+        project_id: project.project_id.clone(),
+        owner_user_id: project.owner_user_id,
+        title: project.title,
+        viewport_x: input.viewport.x,
+        viewport_y: input.viewport.y,
+        viewport_scale: input.viewport.scale.clamp(0.01, 8.0),
+        layers_json,
+        created_at: project.created_at,
+        updated_at: now,
+    });
+
+    build_project_snapshot(ctx, project_id.as_str())
+}
+
+fn create_editor_project_resource(
+    ctx: &ReducerContext,
+    input: EditorProjectResourceCreateInput,
+) -> Result<EditorProjectResourceSnapshot, String> {
+    let resource_id =
+        normalize_required(&input.resource_id, "editor_project_resource.resource_id")?;
+    let project_id = normalize_required(&input.project_id, "editor_project_resource.project_id")?;
+    let owner_user_id = normalize_required(
+        &input.owner_user_id,
+        "editor_project_resource.owner_user_id",
+    )?;
+    require_owned_project(ctx, project_id.as_str(), owner_user_id.as_str())?;
+    let image_src = normalize_required(&input.image_src, "editor_project_resource.image_src")?;
+    let source_type =
+        normalize_required(&input.source_type, "editor_project_resource.source_type")?;
+    if !EDITOR_PROJECT_SOURCE_TYPES.contains(&source_type.as_str()) {
+        return Err("画布资源来源类型只支持 uploaded、generated 或 mock_generated".to_string());
+    }
+    if input.width == 0 || input.height == 0 {
+        return Err("画布资源尺寸必须大于 0".to_string());
+    }
+    if ctx
+        .db
+        .editor_project_resource()
+        .resource_id()
+        .find(&resource_id)
+        .is_some()
+    {
+        return Err("画布资源已存在".to_string());
+    }
+
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    ctx.db
+        .editor_project_resource()
+        .insert(EditorProjectResource {
+            resource_id: resource_id.clone(),
+            project_id,
+            owner_user_id,
+            asset_object_id: normalize_optional(input.asset_object_id),
+            image_src,
+            object_key: normalize_optional(input.object_key),
+            width: input.width,
+            height: input.height,
+            source_type,
+            prompt: normalize_optional(input.prompt),
+            actual_prompt: normalize_optional(input.actual_prompt),
+            model: normalize_optional(input.model),
+            provider: normalize_optional(input.provider),
+            task_id: normalize_optional(input.task_id),
+            source_resource_id: normalize_optional(input.source_resource_id),
+            created_at: now,
+            updated_at: now,
+            asset_kind: normalize_optional(input.asset_kind),
+            generation_inputs_json: normalize_optional(input.generation_inputs_json),
+        });
+
+    ctx.db
+        .editor_project_resource()
+        .resource_id()
+        .find(&resource_id)
+        .map(resource_snapshot_from_row)
+        .ok_or_else(|| "画布资源创建失败".to_string())
+}
+
+fn get_editor_asset_library(
+    ctx: &ReducerContext,
+    input: EditorAssetLibraryGetInput,
+) -> Result<EditorAssetLibrarySnapshot, String> {
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_asset.owner_user_id")?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ensure_default_asset_folder(ctx, owner_user_id.as_str(), now)?;
+    build_asset_library_snapshot(ctx, owner_user_id.as_str())
+}
+
+fn create_editor_asset_folder(
+    ctx: &ReducerContext,
+    input: EditorAssetFolderCreateInput,
+) -> Result<EditorAssetFolderSnapshot, String> {
+    let folder_id = normalize_required(&input.folder_id, "editor_asset_folder.folder_id")?;
+    let owner_user_id =
+        normalize_required(&input.owner_user_id, "editor_asset_folder.owner_user_id")?;
+    if ctx
+        .db
+        .editor_asset_folder()
+        .folder_id()
+        .find(&folder_id)
+        .is_some()
+    {
+        return Err("素材文件夹已存在".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ensure_default_asset_folder(ctx, owner_user_id.as_str(), now)?;
+    ctx.db.editor_asset_folder().insert(EditorAssetFolder {
+        folder_id: folder_id.clone(),
+        owner_user_id,
+        label: normalize_asset_label(&input.label),
+        sort_order: input.sort_order,
+        collapsed: false,
+        system_default: false,
+        created_at: now,
+        updated_at: now,
+    });
+    ctx.db
+        .editor_asset_folder()
+        .folder_id()
+        .find(&folder_id)
+        .map(asset_folder_snapshot_from_row)
+        .ok_or_else(|| "素材文件夹创建失败".to_string())
+}
+
+fn update_editor_asset_folder(
+    ctx: &ReducerContext,
+    input: EditorAssetFolderUpdateInput,
+) -> Result<EditorAssetFolderSnapshot, String> {
+    let folder_id = normalize_required(&input.folder_id, "editor_asset_folder.folder_id")?;
+    let owner_user_id =
+        normalize_required(&input.owner_user_id, "editor_asset_folder.owner_user_id")?;
+    let folder = require_owned_asset_folder(ctx, folder_id.as_str(), owner_user_id.as_str())?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    ctx.db.editor_asset_folder().folder_id().delete(&folder_id);
+    ctx.db.editor_asset_folder().insert(EditorAssetFolder {
+        folder_id: folder.folder_id.clone(),
+        owner_user_id: folder.owner_user_id,
+        label: input
+            .label
+            .map(|label| normalize_asset_label(label.as_str()))
+            .unwrap_or(folder.label),
+        sort_order: folder.sort_order,
+        collapsed: input.collapsed.unwrap_or(folder.collapsed),
+        system_default: folder.system_default,
+        created_at: folder.created_at,
+        updated_at: now,
+    });
+    ctx.db
+        .editor_asset_folder()
+        .folder_id()
+        .find(&folder_id)
+        .map(asset_folder_snapshot_from_row)
+        .ok_or_else(|| "素材文件夹更新失败".to_string())
+}
+
+fn delete_editor_asset_folder(
+    ctx: &ReducerContext,
+    input: EditorAssetFolderDeleteInput,
+) -> Result<EditorAssetLibrarySnapshot, String> {
+    let folder_id = normalize_required(&input.folder_id, "editor_asset_folder.folder_id")?;
+    let owner_user_id =
+        normalize_required(&input.owner_user_id, "editor_asset_folder.owner_user_id")?;
+    let folder = require_owned_asset_folder(ctx, folder_id.as_str(), owner_user_id.as_str())?;
+    if folder.system_default {
+        return Err("默认素材文件夹不能删除".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    let default_folder = ensure_default_asset_folder(ctx, owner_user_id.as_str(), now)?;
+    let moved_assets = ctx
+        .db
+        .editor_asset()
+        .by_editor_asset_folder_id()
+        .filter(&folder_id)
+        .filter(|asset| asset.owner_user_id == owner_user_id)
+        .collect::<Vec<_>>();
+    for asset in moved_assets {
+        ctx.db.editor_asset().asset_id().delete(&asset.asset_id);
+        ctx.db.editor_asset().insert(EditorAsset {
+            folder_id: default_folder.folder_id.clone(),
+            updated_at: now,
+            ..asset
+        });
+    }
+    ctx.db.editor_asset_folder().folder_id().delete(&folder_id);
+    build_asset_library_snapshot(ctx, owner_user_id.as_str())
+}
+
+fn create_editor_asset(
+    ctx: &ReducerContext,
+    input: EditorAssetCreateInput,
+) -> Result<EditorAssetSnapshot, String> {
+    let asset_id = normalize_required(&input.asset_id, "editor_asset.asset_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_asset.owner_user_id")?;
+    let folder_id = normalize_required(&input.folder_id, "editor_asset.folder_id")?;
+    let image_src = normalize_required(&input.image_src, "editor_asset.image_src")?;
+    let source_type = normalize_required(&input.source_type, "editor_asset.source_type")?;
+    if !EDITOR_PROJECT_SOURCE_TYPES.contains(&source_type.as_str()) {
+        return Err("素材来源类型只支持 uploaded、generated 或 mock_generated".to_string());
+    }
+    if input.width == 0 || input.height == 0 {
+        return Err("素材尺寸必须大于 0".to_string());
+    }
+    if ctx.db.editor_asset().asset_id().find(&asset_id).is_some() {
+        return Err("素材已存在".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ensure_default_asset_folder(ctx, owner_user_id.as_str(), now)?;
+    require_owned_asset_folder(ctx, folder_id.as_str(), owner_user_id.as_str())?;
+    ctx.db.editor_asset().insert(EditorAsset {
+        asset_id: asset_id.clone(),
+        owner_user_id,
+        folder_id,
+        label: normalize_asset_label(&input.label),
+        asset_object_id: normalize_optional(input.asset_object_id),
+        image_src,
+        object_key: normalize_optional(input.object_key),
+        width: input.width,
+        height: input.height,
+        source_type,
+        prompt: normalize_optional(input.prompt),
+        actual_prompt: normalize_optional(input.actual_prompt),
+        model: normalize_optional(input.model),
+        provider: normalize_optional(input.provider),
+        task_id: normalize_optional(input.task_id),
+        created_at: now,
+        updated_at: now,
+        asset_kind: normalize_optional(input.asset_kind),
+        generation_inputs_json: normalize_optional(input.generation_inputs_json),
+    });
+    ctx.db
+        .editor_asset()
+        .asset_id()
+        .find(&asset_id)
+        .map(asset_snapshot_from_row)
+        .ok_or_else(|| "素材创建失败".to_string())
+}
+
+fn update_editor_asset(
+    ctx: &ReducerContext,
+    input: EditorAssetUpdateInput,
+) -> Result<EditorAssetSnapshot, String> {
+    let asset_id = normalize_required(&input.asset_id, "editor_asset.asset_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_asset.owner_user_id")?;
+    let asset = require_owned_asset(ctx, asset_id.as_str(), owner_user_id.as_str())?;
+    let folder_id = input
+        .folder_id
+        .map(|value| normalize_required(&value, "editor_asset.folder_id"))
+        .transpose()?
+        .unwrap_or_else(|| asset.folder_id.clone());
+    require_owned_asset_folder(ctx, folder_id.as_str(), owner_user_id.as_str())?;
+    let now = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);
+    ctx.db.editor_asset().asset_id().delete(&asset_id);
+    ctx.db.editor_asset().insert(EditorAsset {
+        asset_id: asset.asset_id.clone(),
+        owner_user_id: asset.owner_user_id,
+        folder_id,
+        label: input
+            .label
+            .map(|label| normalize_asset_label(label.as_str()))
+            .unwrap_or(asset.label),
+        asset_object_id: asset.asset_object_id,
+        image_src: asset.image_src,
+        object_key: asset.object_key,
+        width: asset.width,
+        height: asset.height,
+        source_type: asset.source_type,
+        prompt: asset.prompt,
+        actual_prompt: asset.actual_prompt,
+        model: asset.model,
+        provider: asset.provider,
+        task_id: asset.task_id,
+        created_at: asset.created_at,
+        updated_at: now,
+        asset_kind: asset.asset_kind,
+        generation_inputs_json: asset.generation_inputs_json,
+    });
+    ctx.db
+        .editor_asset()
+        .asset_id()
+        .find(&asset_id)
+        .map(asset_snapshot_from_row)
+        .ok_or_else(|| "素材更新失败".to_string())
+}
+
+fn delete_editor_asset(
+    ctx: &ReducerContext,
+    input: EditorAssetDeleteInput,
+) -> Result<EditorAssetSnapshot, String> {
+    let asset_id = normalize_required(&input.asset_id, "editor_asset.asset_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "editor_asset.owner_user_id")?;
+    let asset = require_owned_asset(ctx, asset_id.as_str(), owner_user_id.as_str())?;
+    ctx.db.editor_asset().asset_id().delete(&asset_id);
+    Ok(asset_snapshot_from_row(asset))
+}
+
+fn build_project_snapshot(
+    ctx: &ReducerContext,
+    project_id: &str,
+) -> Result<EditorProjectSnapshot, String> {
+    let project_key = project_id.to_string();
+    let project = ctx
+        .db
+        .editor_project()
+        .project_id()
+        .find(&project_key)
+        .ok_or_else(|| "图片画布工程不存在".to_string())?;
+    let canvas = ensure_default_canvas(
+        ctx,
+        project.project_id.as_str(),
+        project.owner_user_id.as_str(),
+        Some(&project),
+        project.created_at,
+    )?;
+    let mut resources = ctx
+        .db
+        .editor_project_resource()
+        .by_editor_project_resource_project_id()
+        .filter(&project_key)
+        .map(resource_snapshot_from_row)
+        .collect::<Vec<_>>();
+    resources.sort_by(|left, right| {
+        left.created_at_micros
+            .cmp(&right.created_at_micros)
+            .then_with(|| left.resource_id.cmp(&right.resource_id))
+    });
+
+    Ok(EditorProjectSnapshot {
+        project_id: project.project_id,
+        owner_user_id: project.owner_user_id,
+        title: project.title,
+        canvas: canvas_snapshot_from_row(canvas),
+        resources,
+        created_at_micros: project.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: project.updated_at.to_micros_since_unix_epoch(),
+    })
+}
+
+fn ensure_default_canvas(
+    ctx: &ReducerContext,
+    project_id: &str,
+    owner_user_id: &str,
+    legacy_project: Option<&EditorProject>,
+    now: Timestamp,
+) -> Result<EditorCanvas, String> {
+    let canvas_id = default_canvas_id(project_id);
+    if let Some(canvas) = ctx.db.editor_canvas().canvas_id().find(&canvas_id) {
+        return Ok(canvas);
+    }
+
+    let legacy_view = legacy_project
+        .map(|project| {
+            (
+                project.viewport_x,
+                project.viewport_y,
+                project.viewport_scale,
+                project.layers_json.clone(),
+                project.created_at,
+                project.updated_at,
+            )
+        })
+        .unwrap_or((0.0, 0.0, 1.0, "[]".to_string(), now, now));
+    let canvas = EditorCanvas {
+        canvas_id: canvas_id.clone(),
+        project_id: project_id.to_string(),
+        owner_user_id: owner_user_id.to_string(),
+        title: EDITOR_CANVAS_DEFAULT_TITLE.to_string(),
+        viewport_x: legacy_view.0,
+        viewport_y: legacy_view.1,
+        viewport_scale: legacy_view.2,
+        layers_json: legacy_view.3,
+        created_at: legacy_view.4,
+        updated_at: legacy_view.5,
+    };
+    ctx.db.editor_canvas().insert(canvas);
+    ctx.db
+        .editor_canvas()
+        .canvas_id()
+        .find(&canvas_id)
+        .ok_or_else(|| "图片画布创建失败".to_string())
+}
+
+fn default_canvas_id(project_id: &str) -> String {
+    format!("{project_id}:canvas:default")
+}
+
+fn canvas_snapshot_from_row(row: EditorCanvas) -> EditorCanvasSnapshot {
+    EditorCanvasSnapshot {
+        canvas_id: row.canvas_id,
+        project_id: row.project_id,
+        title: row.title,
+        viewport: EditorProjectViewportSnapshot {
+            x: row.viewport_x,
+            y: row.viewport_y,
+            scale: row.viewport_scale,
+        },
+        layers_json: row.layers_json,
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
+fn require_owned_project(
+    ctx: &ReducerContext,
+    project_id: &str,
+    owner_user_id: &str,
+) -> Result<EditorProject, String> {
+    let project_key = project_id.to_string();
+    let project = ctx
+        .db
+        .editor_project()
+        .project_id()
+        .find(&project_key)
+        .ok_or_else(|| "图片画布工程不存在".to_string())?;
+    if project.owner_user_id != owner_user_id {
+        return Err("无权访问该图片画布工程".to_string());
+    }
+    Ok(project)
+}
+
+fn ensure_default_asset_folder(
+    ctx: &ReducerContext,
+    owner_user_id: &str,
+    now: Timestamp,
+) -> Result<EditorAssetFolder, String> {
+    let folder_id = default_asset_folder_id(owner_user_id);
+    if let Some(folder) = ctx.db.editor_asset_folder().folder_id().find(&folder_id) {
+        return Ok(folder);
+    }
+    ctx.db.editor_asset_folder().insert(EditorAssetFolder {
+        folder_id: folder_id.clone(),
+        owner_user_id: owner_user_id.to_string(),
+        label: EDITOR_ASSET_DEFAULT_FOLDER_LABEL.to_string(),
+        sort_order: 0,
+        collapsed: false,
+        system_default: true,
+        created_at: now,
+        updated_at: now,
+    });
+    ctx.db
+        .editor_asset_folder()
+        .folder_id()
+        .find(&folder_id)
+        .ok_or_else(|| "默认素材文件夹创建失败".to_string())
+}
+
+fn default_asset_folder_id(owner_user_id: &str) -> String {
+    format!("{owner_user_id}:asset-folder:{EDITOR_ASSET_DEFAULT_FOLDER_ID}")
+}
+
+fn require_owned_asset_folder(
+    ctx: &ReducerContext,
+    folder_id: &str,
+    owner_user_id: &str,
+) -> Result<EditorAssetFolder, String> {
+    let folder_key = folder_id.to_string();
+    let folder = ctx
+        .db
+        .editor_asset_folder()
+        .folder_id()
+        .find(&folder_key)
+        .ok_or_else(|| "素材文件夹不存在".to_string())?;
+    if folder.owner_user_id != owner_user_id {
+        return Err("无权访问该素材文件夹".to_string());
+    }
+    Ok(folder)
+}
+
+fn require_owned_asset(
+    ctx: &ReducerContext,
+    asset_id: &str,
+    owner_user_id: &str,
+) -> Result<EditorAsset, String> {
+    let asset_key = asset_id.to_string();
+    let asset = ctx
+        .db
+        .editor_asset()
+        .asset_id()
+        .find(&asset_key)
+        .ok_or_else(|| "素材不存在".to_string())?;
+    if asset.owner_user_id != owner_user_id {
+        return Err("无权访问该素材".to_string());
+    }
+    Ok(asset)
+}
+
+fn build_asset_library_snapshot(
+    ctx: &ReducerContext,
+    owner_user_id: &str,
+) -> Result<EditorAssetLibrarySnapshot, String> {
+    let owner_key = owner_user_id.to_string();
+    let mut folders = ctx
+        .db
+        .editor_asset_folder()
+        .by_editor_asset_folder_owner_user_id()
+        .filter(&owner_key)
+        .map(asset_folder_snapshot_from_row)
+        .collect::<Vec<_>>();
+    folders.sort_by(|left, right| {
+        left.sort_order
+            .cmp(&right.sort_order)
+            .then_with(|| left.created_at_micros.cmp(&right.created_at_micros))
+            .then_with(|| left.folder_id.cmp(&right.folder_id))
+    });
+    let mut assets = ctx
+        .db
+        .editor_asset()
+        .by_editor_asset_owner_user_id()
+        .filter(&owner_key)
+        .map(asset_snapshot_from_row)
+        .collect::<Vec<_>>();
+    assets.sort_by(|left, right| {
+        left.created_at_micros
+            .cmp(&right.created_at_micros)
+            .then_with(|| left.asset_id.cmp(&right.asset_id))
+    });
+    Ok(EditorAssetLibrarySnapshot { folders, assets })
+}
+
+fn asset_folder_snapshot_from_row(row: EditorAssetFolder) -> EditorAssetFolderSnapshot {
+    EditorAssetFolderSnapshot {
+        folder_id: row.folder_id,
+        label: row.label,
+        sort_order: row.sort_order,
+        collapsed: row.collapsed,
+        system_default: row.system_default,
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
+fn asset_snapshot_from_row(row: EditorAsset) -> EditorAssetSnapshot {
+    EditorAssetSnapshot {
+        asset_id: row.asset_id,
+        folder_id: row.folder_id,
+        label: row.label,
+        asset_object_id: row.asset_object_id,
+        image_src: row.image_src,
+        object_key: row.object_key,
+        width: row.width,
+        height: row.height,
+        source_type: row.source_type,
+        prompt: row.prompt,
+        actual_prompt: row.actual_prompt,
+        model: row.model,
+        provider: row.provider,
+        task_id: row.task_id,
+        asset_kind: row.asset_kind,
+        generation_inputs_json: row.generation_inputs_json,
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
+fn resource_snapshot_from_row(row: EditorProjectResource) -> EditorProjectResourceSnapshot {
+    EditorProjectResourceSnapshot {
+        resource_id: row.resource_id,
+        project_id: row.project_id,
+        asset_object_id: row.asset_object_id,
+        image_src: row.image_src,
+        object_key: row.object_key,
+        width: row.width,
+        height: row.height,
+        source_type: row.source_type,
+        prompt: row.prompt,
+        actual_prompt: row.actual_prompt,
+        model: row.model,
+        provider: row.provider,
+        task_id: row.task_id,
+        source_resource_id: row.source_resource_id,
+        asset_kind: row.asset_kind,
+        generation_inputs_json: row.generation_inputs_json,
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
+fn normalize_required(value: &str, field: &str) -> Result<String, String> {
+    let normalized = value.trim();
+    if normalized.is_empty() {
+        return Err(format!("{field} 不能为空"));
+    }
+    Ok(normalized.to_string())
+}
+
+fn normalize_optional(value: Option<String>) -> Option<String> {
+    value
+        .map(|item| item.trim().to_string())
+        .filter(|item| !item.is_empty())
+}
+
+fn normalize_title(value: &str) -> String {
+    let title = value.trim();
+    if title.is_empty() {
+        return EDITOR_PROJECT_DEFAULT_TITLE.to_string();
+    }
+    title.chars().take(EDITOR_PROJECT_MAX_TITLE_CHARS).collect()
+}
+
+fn normalize_asset_label(value: &str) -> String {
+    let label = value.trim();
+    if label.is_empty() {
+        return "未命名素材".to_string();
+    }
+    label.chars().take(EDITOR_ASSET_MAX_LABEL_CHARS).collect()
+}
+
+fn normalize_layout_json(value: String) -> Result<String, String> {
+    if value.len() > EDITOR_PROJECT_MAX_LAYOUT_JSON_BYTES {
+        return Err("图片画布图层布局过大".to_string());
+    }
+    serde_json::from_str::<JsonValue>(&value)
+        .map_err(|_| "图片画布图层布局不是合法 JSON".to_string())?;
+    Ok(value)
+}
+
+fn migrate_canvas_layer_asset_metadata(
+    ctx: &ReducerContext,
+    project_id: &str,
+    owner_user_id: &str,
+    layers_json: String,
+    now: Timestamp,
+) -> Result<String, String> {
+    let mut layout = serde_json::from_str::<JsonValue>(&layers_json)
+        .map_err(|_| "图片画布图层布局不是合法 JSON".to_string())?;
+    let Some(items) = layout.as_array_mut() else {
+        return Ok(layers_json);
+    };
+    let mut changed = false;
+    for item in items {
+        let Some(object) = item.as_object_mut() else {
+            continue;
+        };
+        if object.get("itemType").and_then(JsonValue::as_str).is_some() {
+            continue;
+        }
+        let resource_id = object
+            .get("resourceId")
+            .and_then(JsonValue::as_str)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(ToOwned::to_owned);
+        let asset_kind = object
+            .remove("assetKind")
+            .and_then(|value| normalize_legacy_layout_string(value.as_str()));
+        let generation_inputs_json = object
+            .remove("generationInputs")
+            .and_then(|value| serialize_non_empty_json_value(&value));
+        changed |= asset_kind.is_some() || generation_inputs_json.is_some();
+        let Some(resource_id) = resource_id else {
+            continue;
+        };
+        if asset_kind.is_some() || generation_inputs_json.is_some() {
+            migrate_project_resource_asset_metadata(
+                ctx,
+                project_id,
+                owner_user_id,
+                resource_id,
+                asset_kind,
+                generation_inputs_json,
+                now,
+            );
+        }
+    }
+    if !changed {
+        return Ok(layers_json);
+    }
+    serde_json::to_string(&layout).map_err(|_| "图片画布图层布局无法序列化".to_string())
+}
+
+fn migrate_project_resource_asset_metadata(
+    ctx: &ReducerContext,
+    project_id: &str,
+    owner_user_id: &str,
+    resource_id: String,
+    asset_kind: Option<String>,
+    generation_inputs_json: Option<String>,
+    now: Timestamp,
+) {
+    let Some(resource) = ctx
+        .db
+        .editor_project_resource()
+        .resource_id()
+        .find(&resource_id)
+        .filter(|resource| {
+            resource.project_id == project_id && resource.owner_user_id == owner_user_id
+        })
+    else {
+        return;
+    };
+    let next_asset_kind = resource.asset_kind.clone().or(asset_kind);
+    let next_generation_inputs_json = resource
+        .generation_inputs_json
+        .clone()
+        .or(generation_inputs_json);
+    if next_asset_kind == resource.asset_kind
+        && next_generation_inputs_json == resource.generation_inputs_json
+    {
+        return;
+    }
+    ctx.db
+        .editor_project_resource()
+        .resource_id()
+        .delete(&resource.resource_id);
+    ctx.db
+        .editor_project_resource()
+        .insert(EditorProjectResource {
+            updated_at: now,
+            asset_kind: next_asset_kind,
+            generation_inputs_json: next_generation_inputs_json,
+            ..resource
+        });
+}
+
+fn normalize_legacy_layout_string(value: Option<&str>) -> Option<String> {
+    value
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToOwned::to_owned)
+}
+
+fn serialize_non_empty_json_value(value: &JsonValue) -> Option<String> {
+    if value.is_null() {
+        return None;
+    }
+    if value.as_object().is_some_and(JsonMap::is_empty)
+        || value.as_array().is_some_and(Vec::is_empty)
+    {
+        return None;
+    }
+    serde_json::to_string(value).ok()
+}
+
+fn editor_project_ok(project: Option<EditorProjectSnapshot>) -> EditorProjectProcedureResult {
+    EditorProjectProcedureResult {
+        ok: true,
+        project,
+        error_message: None,
+    }
+}
+
+fn editor_project_error(message: String) -> EditorProjectProcedureResult {
+    EditorProjectProcedureResult {
+        ok: false,
+        project: None,
+        error_message: Some(message),
+    }
+}
+
+fn editor_asset_library_ok(
+    library: EditorAssetLibrarySnapshot,
+) -> EditorAssetLibraryProcedureResult {
+    EditorAssetLibraryProcedureResult {
+        ok: true,
+        library: Some(library),
+        error_message: None,
+    }
+}
+
+fn editor_asset_library_error(message: String) -> EditorAssetLibraryProcedureResult {
+    EditorAssetLibraryProcedureResult {
+        ok: false,
+        library: None,
+        error_message: Some(message),
+    }
+}
+
+fn editor_asset_folder_ok(
+    folder: Option<EditorAssetFolderSnapshot>,
+    library: Option<EditorAssetLibrarySnapshot>,
+) -> EditorAssetFolderProcedureResult {
+    EditorAssetFolderProcedureResult {
+        ok: true,
+        folder,
+        library,
+        error_message: None,
+    }
+}
+
+fn editor_asset_folder_error(message: String) -> EditorAssetFolderProcedureResult {
+    EditorAssetFolderProcedureResult {
+        ok: false,
+        folder: None,
+        library: None,
+        error_message: Some(message),
+    }
+}
+
+fn editor_asset_ok(asset: Option<EditorAssetSnapshot>) -> EditorAssetProcedureResult {
+    EditorAssetProcedureResult {
+        ok: true,
+        asset,
+        error_message: None,
+    }
+}
+
+fn editor_asset_error(message: String) -> EditorAssetProcedureResult {
+    EditorAssetProcedureResult {
+        ok: false,
+        asset: None,
+        error_message: Some(message),
+    }
+}
diff --git a/server-rs/crates/spacetime-module/src/external_api_key_storage.rs b/server-rs/crates/spacetime-module/src/external_api_key_storage.rs
new file mode 100644
index 000000000..b54abff6f
--- /dev/null
+++ b/server-rs/crates/spacetime-module/src/external_api_key_storage.rs
@@ -0,0 +1,312 @@
+use crate::*;
+
+const EXTERNAL_API_KEY_MAX_NAME_CHARS: usize = 80;
+const EXTERNAL_API_KEY_DEFAULT_NAME: &str = "外部 API Key";
+const EXTERNAL_API_KEY_DEFAULT_SCOPES_JSON: &str =
+    "[\"editor:project\",\"editor:canvas\",\"editor:image-generate\",\"editor:asset\"]";
+
+#[spacetimedb::table(
+    accessor = external_api_key,
+    index(accessor = by_external_api_key_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct ExternalApiKey {
+    #[primary_key]
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    #[unique]
+    pub key_hash: String,
+    pub scopes_json: String,
+    pub created_at: Timestamp,
+    pub last_used_at: Option<Timestamp>,
+    pub revoked_at: Option<Timestamp>,
+    pub updated_at: Timestamp,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeyCreateInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub key_hash: String,
+    pub scopes_json: String,
+    pub now_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeyListInput {
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeyRevokeInput {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub revoked_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeyAuthenticateInput {
+    pub key_hash: String,
+    pub used_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeySnapshot {
+    pub key_id: String,
+    pub owner_user_id: String,
+    pub name: String,
+    pub key_prefix: String,
+    pub scopes_json: String,
+    pub created_at_micros: i64,
+    pub last_used_at_micros: Option<i64>,
+    pub revoked_at_micros: Option<i64>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct ExternalApiKeyProcedureResult {
+    pub ok: bool,
+    pub key: Option<ExternalApiKeySnapshot>,
+    pub keys: Vec<ExternalApiKeySnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[spacetimedb::procedure]
+pub fn create_external_api_key_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalApiKeyCreateInput,
+) -> ExternalApiKeyProcedureResult {
+    match ctx.try_with_tx(|tx| create_external_api_key(tx, input.clone())) {
+        Ok(key) => external_api_key_single_ok(key),
+        Err(message) => external_api_key_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn list_external_api_keys_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalApiKeyListInput,
+) -> ExternalApiKeyProcedureResult {
+    match ctx.try_with_tx(|tx| list_external_api_keys(tx, input.clone())) {
+        Ok(keys) => external_api_key_list_ok(keys),
+        Err(message) => external_api_key_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn revoke_external_api_key_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalApiKeyRevokeInput,
+) -> ExternalApiKeyProcedureResult {
+    match ctx.try_with_tx(|tx| revoke_external_api_key(tx, input.clone())) {
+        Ok(key) => external_api_key_single_ok(key),
+        Err(message) => external_api_key_error(message),
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn authenticate_external_api_key_and_return(
+    ctx: &mut ProcedureContext,
+    input: ExternalApiKeyAuthenticateInput,
+) -> ExternalApiKeyProcedureResult {
+    match ctx.try_with_tx(|tx| authenticate_external_api_key(tx, input.clone())) {
+        Ok(key) => external_api_key_single_ok(key),
+        Err(message) => external_api_key_error(message),
+    }
+}
+
+fn create_external_api_key(
+    ctx: &ReducerContext,
+    input: ExternalApiKeyCreateInput,
+) -> Result<ExternalApiKeySnapshot, String> {
+    let key_id = normalize_required(&input.key_id, "external_api_key.key_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "external_api_key.owner_user_id")?;
+    let key_prefix = normalize_required(&input.key_prefix, "external_api_key.key_prefix")?;
+    let key_hash = normalize_required(&input.key_hash, "external_api_key.key_hash")?;
+    let scopes_json = normalize_scopes_json(input.scopes_json)?;
+    if ctx.db.external_api_key().key_id().find(&key_id).is_some() {
+        return Err("API Key 已存在".to_string());
+    }
+    if ctx
+        .db
+        .external_api_key()
+        .key_hash()
+        .find(&key_hash)
+        .is_some()
+    {
+        return Err("API Key 摘要已存在".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.now_micros);
+    ctx.db.external_api_key().insert(ExternalApiKey {
+        key_id: key_id.clone(),
+        owner_user_id,
+        name: normalize_key_name(input.name.as_str()),
+        key_prefix,
+        key_hash,
+        scopes_json,
+        created_at: now,
+        last_used_at: None,
+        revoked_at: None,
+        updated_at: now,
+    });
+    ctx.db
+        .external_api_key()
+        .key_id()
+        .find(&key_id)
+        .map(external_api_key_snapshot_from_row)
+        .ok_or_else(|| "API Key 创建失败".to_string())
+}
+
+fn list_external_api_keys(
+    ctx: &ReducerContext,
+    input: ExternalApiKeyListInput,
+) -> Result<Vec<ExternalApiKeySnapshot>, String> {
+    let owner_user_id = normalize_required(&input.owner_user_id, "external_api_key.owner_user_id")?;
+    let mut keys = ctx
+        .db
+        .external_api_key()
+        .by_external_api_key_owner_user_id()
+        .filter(&owner_user_id)
+        .map(external_api_key_snapshot_from_row)
+        .collect::<Vec<_>>();
+    keys.sort_by(|left, right| {
+        right
+            .created_at_micros
+            .cmp(&left.created_at_micros)
+            .then_with(|| right.key_id.cmp(&left.key_id))
+    });
+    Ok(keys)
+}
+
+fn revoke_external_api_key(
+    ctx: &ReducerContext,
+    input: ExternalApiKeyRevokeInput,
+) -> Result<ExternalApiKeySnapshot, String> {
+    let key_id = normalize_required(&input.key_id, "external_api_key.key_id")?;
+    let owner_user_id = normalize_required(&input.owner_user_id, "external_api_key.owner_user_id")?;
+    let row = ctx
+        .db
+        .external_api_key()
+        .key_id()
+        .find(&key_id)
+        .ok_or_else(|| "API Key 不存在".to_string())?;
+    if row.owner_user_id != owner_user_id {
+        return Err("无权访问该 API Key".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.revoked_at_micros);
+    ctx.db.external_api_key().key_id().delete(&key_id);
+    ctx.db.external_api_key().insert(ExternalApiKey {
+        revoked_at: row.revoked_at.or(Some(now)),
+        updated_at: now,
+        ..row
+    });
+    ctx.db
+        .external_api_key()
+        .key_id()
+        .find(&key_id)
+        .map(external_api_key_snapshot_from_row)
+        .ok_or_else(|| "API Key 撤销失败".to_string())
+}
+
+fn authenticate_external_api_key(
+    ctx: &ReducerContext,
+    input: ExternalApiKeyAuthenticateInput,
+) -> Result<ExternalApiKeySnapshot, String> {
+    let key_hash = normalize_required(&input.key_hash, "external_api_key.key_hash")?;
+    let row = ctx
+        .db
+        .external_api_key()
+        .key_hash()
+        .find(&key_hash)
+        .ok_or_else(|| "API Key 不存在或已失效".to_string())?;
+    if row.revoked_at.is_some() {
+        return Err("API Key 不存在或已失效".to_string());
+    }
+    let now = Timestamp::from_micros_since_unix_epoch(input.used_at_micros);
+    ctx.db.external_api_key().key_id().delete(&row.key_id);
+    ctx.db.external_api_key().insert(ExternalApiKey {
+        last_used_at: Some(now),
+        updated_at: now,
+        ..row
+    });
+    ctx.db
+        .external_api_key()
+        .key_hash()
+        .find(&key_hash)
+        .map(external_api_key_snapshot_from_row)
+        .ok_or_else(|| "API Key 校验失败".to_string())
+}
+
+fn external_api_key_snapshot_from_row(row: ExternalApiKey) -> ExternalApiKeySnapshot {
+    ExternalApiKeySnapshot {
+        key_id: row.key_id,
+        owner_user_id: row.owner_user_id,
+        name: row.name,
+        key_prefix: row.key_prefix,
+        scopes_json: row.scopes_json,
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        last_used_at_micros: row
+            .last_used_at
+            .map(|value| value.to_micros_since_unix_epoch()),
+        revoked_at_micros: row
+            .revoked_at
+            .map(|value| value.to_micros_since_unix_epoch()),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
+fn normalize_required(value: &str, field: &str) -> Result<String, String> {
+    let normalized = value.trim();
+    if normalized.is_empty() {
+        return Err(format!("{field} 不能为空"));
+    }
+    Ok(normalized.to_string())
+}
+
+fn normalize_key_name(value: &str) -> String {
+    let name = value.trim();
+    if name.is_empty() {
+        return EXTERNAL_API_KEY_DEFAULT_NAME.to_string();
+    }
+    name.chars().take(EXTERNAL_API_KEY_MAX_NAME_CHARS).collect()
+}
+
+fn normalize_scopes_json(value: String) -> Result<String, String> {
+    let normalized = value.trim();
+    if normalized.is_empty() {
+        return Ok(EXTERNAL_API_KEY_DEFAULT_SCOPES_JSON.to_string());
+    }
+    serde_json::from_str::<JsonValue>(normalized)
+        .map_err(|_| "API Key scopes 必须是合法 JSON".to_string())?;
+    Ok(normalized.to_string())
+}
+
+fn external_api_key_single_ok(key: ExternalApiKeySnapshot) -> ExternalApiKeyProcedureResult {
+    ExternalApiKeyProcedureResult {
+        ok: true,
+        key: Some(key),
+        keys: Vec::new(),
+        error_message: None,
+    }
+}
+
+fn external_api_key_list_ok(keys: Vec<ExternalApiKeySnapshot>) -> ExternalApiKeyProcedureResult {
+    ExternalApiKeyProcedureResult {
+        ok: true,
+        key: None,
+        keys,
+        error_message: None,
+    }
+}
+
+fn external_api_key_error(message: String) -> ExternalApiKeyProcedureResult {
+    ExternalApiKeyProcedureResult {
+        ok: false,
+        key: None,
+        keys: Vec::new(),
+        error_message: Some(message),
+    }
+}
diff --git a/server-rs/crates/spacetime-module/src/lib.rs b/server-rs/crates/spacetime-module/src/lib.rs
index 51cfd9eae..a6fe765b5 100644
--- a/server-rs/crates/spacetime-module/src/lib.rs
+++ b/server-rs/crates/spacetime-module/src/lib.rs
@@ -30,7 +30,9 @@ mod bark_battle;
 mod big_fish;
 mod custom_world;
 mod domain_types;
+mod editor_project_storage;
 mod entry;
+mod external_api_key_storage;
 mod external_generation;
 mod gameplay;
 mod jump_hop;
@@ -51,7 +53,9 @@ pub use bark_battle::*;
 pub use big_fish::*;
 pub use custom_world::*;
 pub use domain_types::*;
+pub use editor_project_storage::*;
 pub use entry::*;
+pub use external_api_key_storage::*;
 pub use external_generation::*;
 pub use gameplay::*;
 pub use jump_hop::*;
diff --git a/server-rs/crates/spacetime-module/src/migration.rs b/server-rs/crates/spacetime-module/src/migration.rs
index 8734e09c1..19eb41724 100644
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -229,6 +229,12 @@ macro_rules! migration_tables {
             asset_object,
             asset_entity_binding,
             asset_event,
+            external_api_key,
+            editor_project,
+            editor_canvas,
+            editor_project_resource,
+            editor_asset_folder,
+            editor_asset,
             puzzle_agent_session,
             puzzle_background_compile_task,
             puzzle_agent_message,
diff --git a/src/App.test.tsx b/src/App.test.tsx
new file mode 100644
index 000000000..1bbffb369
--- /dev/null
+++ b/src/App.test.tsx
@@ -0,0 +1,133 @@
+/* @vitest-environment jsdom */
+
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ComponentProps } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import App from './App';
+import { resolveInitialSelectionStageFromPath } from './routing/appPageRoutes';
+
+function mockMatchMedia(matches: boolean) {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+}
+
+vi.mock('./components/platform-entry/PlatformEntryFlowShell', async () => {
+  const React = await import('react');
+  type PlatformEntryFlowShellProps = ComponentProps<
+    typeof import('./components/platform-entry/PlatformEntryFlowShell').PlatformEntryFlowShell
+  >;
+
+  return {
+    PlatformEntryFlowShell: ({
+      selectionStage,
+      setSelectionStage,
+    }: PlatformEntryFlowShellProps) =>
+      React.createElement(
+        'div',
+        null,
+        React.createElement(
+          'div',
+          { 'data-testid': 'selection-stage' },
+          selectionStage,
+        ),
+        React.createElement(
+          'button',
+          {
+            type: 'button',
+            onClick: () => {
+              setSelectionStage('image-editor', {
+                path: '/editor/canvas?projectid=project-from-test',
+              });
+            },
+          },
+          '打开最近项目',
+        ),
+      ),
+  };
+});
+
+vi.mock('./RpgRuntimeApp', () => ({
+  RpgRuntimeApp: () => <div>运行态</div>,
+}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('resolveInitialSelectionStageFromPath', () => {
+  it('opens the desktop root route on the creation home stage', () => {
+    expect(resolveInitialSelectionStageFromPath('/', true)).toBe(
+      'creation-home',
+    );
+  });
+
+  it('keeps the mobile root route on the platform stage', () => {
+    expect(resolveInitialSelectionStageFromPath('/', false)).toBe('platform');
+  });
+
+  it('keeps explicit routes mapped to their own stages on desktop', () => {
+    expect(resolveInitialSelectionStageFromPath('/creation/puzzle', true)).toBe(
+      'puzzle-agent-workspace',
+    );
+    expect(resolveInitialSelectionStageFromPath('/creation', true)).toBe(
+      'creation-home',
+    );
+  });
+});
+
+describe('App navigation history', () => {
+  it('renders the desktop home URL with the creation home stage', () => {
+    mockMatchMedia(true);
+    window.history.replaceState(null, '', '/');
+
+    render(<App />);
+
+    expect(screen.getByTestId('selection-stage').textContent).toBe(
+      'creation-home',
+    );
+  });
+
+  it('keeps project canvas navigation as one history entry with projectid', async () => {
+    mockMatchMedia(true);
+    window.history.replaceState(null, '', '/creation');
+    const pushStateSpy = vi.spyOn(window.history, 'pushState');
+    const user = userEvent.setup();
+
+    render(<App />);
+
+    await user.click(screen.getByRole('button', { name: '打开最近项目' }));
+
+    await waitFor(() => {
+      expect(window.location.pathname).toBe('/editor/canvas');
+      expect(window.location.search).toBe('?projectid=project-from-test');
+    });
+    expect(pushStateSpy).toHaveBeenCalledTimes(1);
+    expect(pushStateSpy).toHaveBeenCalledWith(
+      null,
+      '',
+      '/editor/canvas?projectid=project-from-test',
+    );
+
+    window.history.back();
+    await waitFor(() => {
+      expect(window.location.pathname).toBe('/creation');
+      expect(window.location.search).toBe('');
+    });
+
+    pushStateSpy.mockRestore();
+  });
+});
diff --git a/src/App.tsx b/src/App.tsx
index e16ff02fb..7fd3d6412 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -9,6 +9,7 @@ import {
 
 import { useAuthUi } from './components/auth/AuthUiContext';
 import { PlatformEntryFlowShell } from './components/platform-entry/PlatformEntryFlowShell';
+import { getInitialPlatformDesktopLayout } from './components/platform-entry/platformEntryResponsive';
 import type {
   CustomWorldRuntimeLaunchOptions,
   SelectionStage,
@@ -19,8 +20,8 @@ import {
   normalizeAppPath,
   pushAppHistoryPath,
   readPublicWorkCodeFromLocationSearch,
+  resolveInitialSelectionStageFromPath,
   resolvePathForSelectionStage,
-  resolveSelectionStageFromPath,
 } from './routing/appPageRoutes';
 import type { RpgRuntimeAppIntent } from './RpgRuntimeApp';
 import type { CustomWorldProfile } from './types';
@@ -59,7 +60,10 @@ export default function App() {
     isRpgRuntimeRoute(window.location.pathname),
   );
   const [selectionStage, setRawSelectionStage] = useState<SelectionStage>(() =>
-    resolveSelectionStageFromPath(window.location.pathname),
+    resolveInitialSelectionStageFromPath(
+      window.location.pathname,
+      getInitialPlatformDesktopLayout(),
+    ),
   );
   const [runtimeReturnStage, setRuntimeReturnStage] =
     useState<SelectionStage>('platform');
@@ -67,10 +71,13 @@ export default function App() {
     readPublicWorkCodeFromLocationSearch(window.location.search),
   );
 
-  const setSelectionStage = useCallback((stage: SelectionStage) => {
-    setRawSelectionStage(stage);
-    pushAppHistoryPath(resolvePathForSelectionStage(stage));
-  }, []);
+  const setSelectionStage = useCallback(
+    (stage: SelectionStage, options?: { path?: string }) => {
+      setRawSelectionStage(stage);
+      pushAppHistoryPath(options?.path ?? resolvePathForSelectionStage(stage));
+    },
+    [],
+  );
 
   useEffect(() => {
     const syncStageFromHistory = () => {
@@ -81,7 +88,10 @@ export default function App() {
 
       setIsRuntimeActive(false);
       setRawSelectionStage(
-        resolveSelectionStageFromPath(window.location.pathname),
+        resolveInitialSelectionStageFromPath(
+          window.location.pathname,
+          getInitialPlatformDesktopLayout(),
+        ),
       );
     };
 
@@ -133,6 +143,10 @@ export default function App() {
     authUi?.platformTheme === 'dark'
       ? 'platform-theme--dark'
       : 'platform-theme--light';
+  const isImageEditorStage = selectionStage === 'image-editor';
+  const platformShellSurfaceClass = isImageEditorStage
+    ? 'bg-white p-0'
+    : 'bg-[image:var(--platform-body-fill)] p-2 sm:p-4';
 
   if (isRuntimeActive) {
     return (
@@ -150,7 +164,7 @@ export default function App() {
 
   return (
     <div
-      className={`platform-ui-shell platform-viewport-shell platform-theme ${platformThemeClass} flex flex-col overflow-hidden bg-[image:var(--platform-body-fill)] p-2 font-sans text-[var(--platform-text-strong)] sm:p-4`}
+      className={`platform-ui-shell platform-viewport-shell platform-theme ${platformThemeClass} flex flex-col overflow-hidden ${platformShellSurfaceClass} font-sans text-[var(--platform-text-strong)]`}
     >
       <PlatformEntryFlowShell
         selectionStage={selectionStage}
diff --git a/src/components/ResolvedAssetImage.tsx b/src/components/ResolvedAssetImage.tsx
index 5f662f7b9..13060b386 100644
--- a/src/components/ResolvedAssetImage.tsx
+++ b/src/components/ResolvedAssetImage.tsx
@@ -8,12 +8,14 @@ type ResolvedAssetImageProps = Omit<
   'src'
 > & {
   src?: string | null;
+  objectKey?: string | null;
   fallbackSrc?: string | null;
   refreshKey?: string | number | null;
 };
 
 export function ResolvedAssetImage({
   src,
+  objectKey,
   fallbackSrc,
   alt,
   refreshKey,
@@ -21,6 +23,7 @@ export function ResolvedAssetImage({
   ...rest
 }: ResolvedAssetImageProps) {
   const { resolvedUrl, isResolving, shouldResolve } = useResolvedAssetReadUrl(src, {
+    objectKey,
     refreshKey,
   });
   const normalizedSource = src?.trim() ?? '';
diff --git a/src/components/ResolvedAssetVideo.tsx b/src/components/ResolvedAssetVideo.tsx
index 4f0a8b020..97658d03d 100644
--- a/src/components/ResolvedAssetVideo.tsx
+++ b/src/components/ResolvedAssetVideo.tsx
@@ -7,17 +7,20 @@ type ResolvedAssetVideoProps = Omit<
   'src'
 > & {
   src?: string | null;
+  objectKey?: string | null;
   fallbackSrc?: string | null;
   refreshKey?: string | number | null;
 };
 
 export function ResolvedAssetVideo({
   src,
+  objectKey,
   fallbackSrc,
   refreshKey,
   ...rest
 }: ResolvedAssetVideoProps) {
   const { resolvedUrl } = useResolvedAssetReadUrl(src, {
+    objectKey,
     refreshKey,
   });
   const finalSrc = resolvedUrl || fallbackSrc?.trim() || '';
diff --git a/src/components/auth/AuthGate.test.tsx b/src/components/auth/AuthGate.test.tsx
index 74201447c..cd28c3762 100644
--- a/src/components/auth/AuthGate.test.tsx
+++ b/src/components/auth/AuthGate.test.tsx
@@ -2,7 +2,7 @@
 
 import { act, render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
 
 import type { AuthSessionSummary, AuthUser } from '../../services/authService';
@@ -250,6 +250,16 @@ function AccountPanelProbe() {
   );
 }
 
+function AutoOpenLoginProbe() {
+  const authUi = useAuthUi();
+
+  useEffect(() => {
+    authUi?.openLoginModal();
+  }, [authUi]);
+
+  return <div>编辑器内容</div>;
+}
+
 test('auth gate keeps platform content visible when phone login is available', async () => {
   authMocks.getAuthLoginOptions.mockResolvedValue({
     availableLoginMethods: ['phone'],
@@ -266,6 +276,22 @@ test('auth gate keeps platform content visible when phone login is available', a
   expect(screen.queryByText('先登录账号，再同步你的冒险进度。')).toBeNull();
 });
 
+test('auth gate portals page-level login requests above fullscreen content', async () => {
+  const { container } = render(
+    <AuthGate>
+      <div className="image-canvas-editor">全屏画布</div>
+      <AutoOpenLoginProbe />
+    </AuthGate>,
+  );
+
+  expect(await screen.findByText('编辑器内容')).toBeTruthy();
+  const dialog = await screen.findByRole('dialog', { name: '账号入口' });
+
+  expect(container.querySelector('[role="dialog"]')).toBeNull();
+  expect(dialog.parentElement?.parentElement).toBe(document.body);
+  expect(dialog.parentElement?.className).toContain('z-[120]');
+});
+
 test('auth gate waits for refresh cookie rotation before exposing restored user content', async () => {
   let resolveToken!: (token: string) => void;
   const tokenPromise = new Promise<string>((resolve) => {
diff --git a/src/components/auth/PlatformAuthModalShell.test.tsx b/src/components/auth/PlatformAuthModalShell.test.tsx
index fd566186a..55765e8f7 100644
--- a/src/components/auth/PlatformAuthModalShell.test.tsx
+++ b/src/components/auth/PlatformAuthModalShell.test.tsx
@@ -8,7 +8,7 @@ import { PlatformAuthModalShell } from './PlatformAuthModalShell';
 test('renders auth modal shell with platform theme and auth card chrome', () => {
   const onClose = vi.fn();
 
-  render(
+  const { container } = render(
     <PlatformAuthModalShell
       title="账号入口"
       platformTheme="light"
@@ -22,6 +22,8 @@ test('renders auth modal shell with platform theme and auth card chrome', () =>
 
   const dialog = screen.getByRole('dialog', { name: '账号入口' });
 
+  expect(container.querySelector('[role="dialog"]')).toBeNull();
+  expect(document.body.contains(dialog)).toBe(true);
   expect(dialog.parentElement?.className).toContain('platform-theme--light');
   expect(dialog.className).toContain('platform-modal-shell');
   expect(dialog.className).toContain('platform-auth-card');
diff --git a/src/components/auth/PlatformAuthModalShell.tsx b/src/components/auth/PlatformAuthModalShell.tsx
index 5364639e8..e7ce21e21 100644
--- a/src/components/auth/PlatformAuthModalShell.tsx
+++ b/src/components/auth/PlatformAuthModalShell.tsx
@@ -55,7 +55,6 @@ export function PlatformAuthModalShell({
       closeVariant="platformIcon"
       closeOnBackdrop
       closeOnEscape={false}
-      portal={false}
       size={size}
       showHeader={showHeader}
       zIndexClassName={zIndexClassName}
diff --git a/src/components/common/PlatformBatchActionToolbar.test.tsx b/src/components/common/PlatformBatchActionToolbar.test.tsx
new file mode 100644
index 000000000..d2eb5f209
--- /dev/null
+++ b/src/components/common/PlatformBatchActionToolbar.test.tsx
@@ -0,0 +1,22 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { PlatformBatchActionToolbar } from './PlatformBatchActionToolbar';
+
+describe('PlatformBatchActionToolbar', () => {
+  it('renders a labelled toolbar around batch actions', () => {
+    render(
+      <PlatformBatchActionToolbar label="素材批量操作">
+        <button type="button">删除</button>
+      </PlatformBatchActionToolbar>,
+    );
+
+    const toolbar = screen.getByRole('toolbar', { name: '素材批量操作' });
+
+    expect(toolbar).toBeTruthy();
+    expect(toolbar.className).toContain('platform-batch-action-toolbar');
+    expect(screen.getByRole('button', { name: '删除' })).toBeTruthy();
+  });
+});
diff --git a/src/components/common/PlatformBatchActionToolbar.tsx b/src/components/common/PlatformBatchActionToolbar.tsx
new file mode 100644
index 000000000..e7c7b6c21
--- /dev/null
+++ b/src/components/common/PlatformBatchActionToolbar.tsx
@@ -0,0 +1,33 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+type PlatformBatchActionToolbarProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children'
+> & {
+  children: ReactNode;
+  label?: string;
+};
+
+/**
+ * 平台批量操作浮动工具栏。
+ * 只统一容器 chrome 与 toolbar 语义，具体选择逻辑和动作按钮由业务组件传入。
+ */
+export function PlatformBatchActionToolbar({
+  children,
+  label = '批量操作',
+  className,
+  ...divProps
+}: PlatformBatchActionToolbarProps) {
+  return (
+    <div
+      {...divProps}
+      className={['platform-batch-action-toolbar', className]
+        .filter(Boolean)
+        .join(' ')}
+      role="toolbar"
+      aria-label={label}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/common/PlatformEmptyState.test.tsx b/src/components/common/PlatformEmptyState.test.tsx
index 5340792b1..5cc553319 100644
--- a/src/components/common/PlatformEmptyState.test.tsx
+++ b/src/components/common/PlatformEmptyState.test.tsx
@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
-import { render, screen } from '@testing-library/react';
-import { expect, test } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { expect, test, vi } from 'vitest';
 
 import { PlatformEmptyState } from './PlatformEmptyState';
 
@@ -71,3 +71,29 @@ test('supports dark editor dashed empty state', () => {
   expect(emptyState.className).toContain('bg-black/20');
   expect(emptyState.className).toContain('text-[var(--platform-text-soft)]');
 });
+
+test('supports button empty state for empty collection actions', () => {
+  const onClick = vi.fn();
+  render(
+    <PlatformEmptyState
+      asChild="button"
+      surface="subpanel"
+      size="panel"
+      className="local-empty-action"
+      onClick={onClick}
+    >
+      新建项目
+    </PlatformEmptyState>,
+  );
+
+  const button = screen.getByRole('button', { name: '新建项目' });
+
+  expect(button.tagName).toBe('BUTTON');
+  expect(button.getAttribute('type')).toBe('button');
+  expect(button.className).toContain('platform-empty-state');
+  expect(button.className).toContain('local-empty-action');
+
+  fireEvent.click(button);
+
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
diff --git a/src/components/common/PlatformEmptyState.tsx b/src/components/common/PlatformEmptyState.tsx
index 25ae271fa..a992c3d30 100644
--- a/src/components/common/PlatformEmptyState.tsx
+++ b/src/components/common/PlatformEmptyState.tsx
@@ -1,19 +1,41 @@
-import type { HTMLAttributes, ReactNode } from 'react';
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
 
 type PlatformEmptyStateSurface = 'soft' | 'dashed' | 'subpanel' | 'editorDark';
 type PlatformEmptyStateSize = 'compact' | 'panel' | 'inline';
 type PlatformEmptyStateTone = 'base' | 'soft';
 
-type PlatformEmptyStateProps = Omit<
-  HTMLAttributes<HTMLDivElement>,
-  'children'
-> & {
+type PlatformEmptyStateBaseProps = {
   children: ReactNode;
   surface?: PlatformEmptyStateSurface;
   size?: PlatformEmptyStateSize;
   tone?: PlatformEmptyStateTone;
 };
 
+type PlatformEmptyStateDivProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children'
+> & {
+  asChild?: false;
+} & PlatformEmptyStateBaseProps;
+
+type PlatformEmptyStateButtonProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'children'
+> & {
+  asChild: 'button';
+} & PlatformEmptyStateBaseProps;
+
+type PlatformEmptyStateProps =
+  | PlatformEmptyStateDivProps
+  | PlatformEmptyStateButtonProps;
+
+type PlatformEmptyStateClassNameOptions = {
+  surface: PlatformEmptyStateSurface;
+  size: PlatformEmptyStateSize;
+  tone: PlatformEmptyStateTone;
+  className?: string;
+};
+
 const PLATFORM_EMPTY_STATE_SURFACE_CLASS: Record<
   PlatformEmptyStateSurface,
   string
@@ -44,30 +66,57 @@ const PLATFORM_EMPTY_STATE_TONE_CLASS: Record<PlatformEmptyStateTone, string> =
  * 平台通用空态和轻量加载态。
  * 收口平台列表、作品架和素材选择弹窗中重复的空面板外观。
  */
+function getPlatformEmptyStateClassName({
+  surface,
+  size,
+  tone,
+  className,
+}: PlatformEmptyStateClassNameOptions) {
+  return [
+    'min-w-0',
+    'platform-empty-state',
+    PLATFORM_EMPTY_STATE_SURFACE_CLASS[surface],
+    PLATFORM_EMPTY_STATE_SIZE_CLASS[size],
+    PLATFORM_EMPTY_STATE_TONE_CLASS[tone],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+}
+
 export function PlatformEmptyState({
   children,
   surface = 'soft',
   size = 'compact',
   tone,
   className,
-  ...divProps
+  asChild,
+  ...emptyStateProps
 }: PlatformEmptyStateProps) {
   const resolvedTone =
     tone ?? (surface === 'subpanel' || size === 'inline' ? 'soft' : 'base');
+  const emptyStateClassName = getPlatformEmptyStateClassName({
+    surface,
+    size,
+    tone: resolvedTone,
+    className,
+  });
+
+  if (asChild === 'button') {
+    const { type = 'button', ...buttonProps } =
+      emptyStateProps as ButtonHTMLAttributes<HTMLButtonElement>;
+
+    return (
+      <button {...buttonProps} type={type} className={emptyStateClassName}>
+        {children}
+      </button>
+    );
+  }
 
   return (
     <div
-      {...divProps}
-      className={[
-        'min-w-0',
-        'platform-empty-state',
-        PLATFORM_EMPTY_STATE_SURFACE_CLASS[surface],
-        PLATFORM_EMPTY_STATE_SIZE_CLASS[size],
-        PLATFORM_EMPTY_STATE_TONE_CLASS[resolvedTone],
-        className,
-      ]
-        .filter(Boolean)
-        .join(' ')}
+      {...(emptyStateProps as HTMLAttributes<HTMLDivElement>)}
+      className={emptyStateClassName}
     >
       {children}
     </div>
diff --git a/src/components/common/PlatformFloatingMenu.test.tsx b/src/components/common/PlatformFloatingMenu.test.tsx
new file mode 100644
index 000000000..e4dad62c3
--- /dev/null
+++ b/src/components/common/PlatformFloatingMenu.test.tsx
@@ -0,0 +1,53 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from './PlatformFloatingMenu';
+
+describe('PlatformFloatingMenu', () => {
+  it('renders menu items with accessible menu semantics', async () => {
+    const onRename = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <PlatformFloatingMenu label="项目菜单" placement="bottom-end">
+        <PlatformFloatingMenuItem onClick={onRename}>
+          重命名
+        </PlatformFloatingMenuItem>
+      </PlatformFloatingMenu>,
+    );
+
+    expect(screen.getByRole('menu', { name: '项目菜单' })).toBeTruthy();
+
+    await user.click(screen.getByRole('menuitem', { name: '重命名' }));
+
+    expect(onRename).toHaveBeenCalledOnce();
+  });
+
+  it('keeps pointer events from leaking to canvas-style parents', () => {
+    const onParentPointerDown = vi.fn();
+    const onMenuPointerDown = vi.fn();
+
+    render(
+      <div onPointerDown={onParentPointerDown}>
+        <PlatformFloatingMenu
+          label="项目菜单"
+          placement="bottom-end"
+          onPointerDown={onMenuPointerDown}
+        >
+          <PlatformFloatingMenuItem>重命名</PlatformFloatingMenuItem>
+        </PlatformFloatingMenu>
+      </div>,
+    );
+
+    fireEvent.pointerDown(screen.getByRole('menu', { name: '项目菜单' }));
+
+    expect(onMenuPointerDown).toHaveBeenCalledOnce();
+    expect(onParentPointerDown).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/components/common/PlatformFloatingMenu.tsx b/src/components/common/PlatformFloatingMenu.tsx
new file mode 100644
index 000000000..1fcf7ab1d
--- /dev/null
+++ b/src/components/common/PlatformFloatingMenu.tsx
@@ -0,0 +1,75 @@
+import type { ButtonHTMLAttributes, CSSProperties, HTMLAttributes, ReactNode } from 'react';
+
+type PlatformFloatingMenuProps = HTMLAttributes<HTMLDivElement> & {
+  children: ReactNode;
+  className?: string;
+  label?: string;
+  placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+  style?: CSSProperties;
+};
+
+type PlatformFloatingMenuItemProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'children'
+> & {
+  icon?: ReactNode;
+  children: ReactNode;
+};
+
+/**
+ * 平台浮层菜单原语。
+ * 用于卡片角标、画布局部菜单等轻量动作集合，统一 role 与菜单项 chrome。
+ */
+export function PlatformFloatingMenu({
+  children,
+  className,
+  label,
+  placement = 'top-end',
+  style,
+  onPointerDown,
+  ...divProps
+}: PlatformFloatingMenuProps) {
+  return (
+    <div
+      {...divProps}
+      className={[
+        'platform-floating-menu',
+        `platform-floating-menu--${placement}`,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      role="menu"
+      aria-label={label}
+      style={style}
+      onPointerDown={(event) => {
+        event.stopPropagation();
+        onPointerDown?.(event);
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export function PlatformFloatingMenuItem({
+  icon,
+  children,
+  className,
+  type = 'button',
+  ...buttonProps
+}: PlatformFloatingMenuItemProps) {
+  return (
+    <button
+      {...buttonProps}
+      type={type}
+      className={['platform-floating-menu__item', className]
+        .filter(Boolean)
+        .join(' ')}
+      role="menuitem"
+    >
+      {icon}
+      <span>{children}</span>
+    </button>
+  );
+}
diff --git a/src/components/common/PlatformIconButton.test.tsx b/src/components/common/PlatformIconButton.test.tsx
index 1533c47bc..29038101d 100644
--- a/src/components/common/PlatformIconButton.test.tsx
+++ b/src/components/common/PlatformIconButton.test.tsx
@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
-import { render, screen } from '@testing-library/react';
-import { expect, test } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { expect, test, vi } from 'vitest';
 
 import { PlatformIconButton } from './PlatformIconButton';
 
@@ -95,6 +95,34 @@ test('supports dark mini icon action chrome', () => {
   expect(button.textContent).toBe('?');
 });
 
+test('supports span button child chrome for nested action surfaces', () => {
+  const onClick = vi.fn();
+  render(
+    <button type="button">
+      <PlatformIconButton
+        asChild="spanButton"
+        label="查看元数据"
+        variant="darkMini"
+        icon={<span aria-hidden="true">{'{}'}</span>}
+        className="absolute"
+        onClick={onClick}
+      />
+    </button>,
+  );
+
+  const action = screen.getByRole('button', { name: '查看元数据' });
+
+  expect(action.tagName).toBe('SPAN');
+  expect(action.className).toContain('bg-black/55');
+  expect(action.className).toContain('absolute');
+  expect(action.getAttribute('tabindex')).toBe('0');
+
+  fireEvent.keyDown(action, { key: 'Enter' });
+  fireEvent.keyDown(action, { key: ' ' });
+
+  expect(onClick).toHaveBeenCalledTimes(2);
+});
+
 test('supports label child chrome for icon upload controls', () => {
   const { container } = render(
     <>
diff --git a/src/components/common/PlatformIconButton.tsx b/src/components/common/PlatformIconButton.tsx
index b15a3a833..4cf90c7f9 100644
--- a/src/components/common/PlatformIconButton.tsx
+++ b/src/components/common/PlatformIconButton.tsx
@@ -1,16 +1,25 @@
+import { forwardRef } from 'react';
 import type {
   ButtonHTMLAttributes,
+  HTMLAttributes,
+  KeyboardEvent,
   LabelHTMLAttributes,
   ReactNode,
+  Ref,
 } from 'react';
 
 type PlatformIconButtonBaseProps = {
   label: string;
   icon: ReactNode;
   children?: ReactNode;
-  variant?: 'platformIcon' | 'surfaceFloating' | 'darkMini';
+  variant?: PlatformIconButtonVariant;
 };
 
+export type PlatformIconButtonVariant =
+  | 'platformIcon'
+  | 'surfaceFloating'
+  | 'darkMini';
+
 type PlatformIconButtonButtonProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   'aria-label' | 'children'
@@ -27,24 +36,40 @@ type PlatformIconButtonLabelProps = Omit<
     asChild: 'label';
   };
 
+type PlatformIconButtonSpanButtonProps = Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'aria-label' | 'children' | 'role'
+> &
+  PlatformIconButtonBaseProps & {
+    asChild: 'spanButton';
+    disabled?: boolean;
+  };
+
 type PlatformIconButtonProps =
   | PlatformIconButtonButtonProps
-  | PlatformIconButtonLabelProps;
+  | PlatformIconButtonLabelProps
+  | PlatformIconButtonSpanButtonProps;
 
 /**
  * 平台通用图标动作按钮。
  * 统一承接纯图标动作、图标上传 label 和带短标签的浮动图标动作。
  */
-export function PlatformIconButton({
-  label,
-  icon,
-  children,
-  variant = 'platformIcon',
-  title,
-  className,
-  asChild,
-  ...actionProps
-}: PlatformIconButtonProps) {
+export const PlatformIconButton = forwardRef<
+  HTMLButtonElement | HTMLLabelElement | HTMLSpanElement,
+  PlatformIconButtonProps
+>(function PlatformIconButton(
+  {
+    label,
+    icon,
+    children,
+    variant = 'platformIcon',
+    title,
+    className,
+    asChild,
+    ...actionProps
+  },
+  ref,
+) {
   const variantClassName = {
     platformIcon: 'platform-icon-button',
     surfaceFloating:
@@ -61,6 +86,7 @@ export function PlatformIconButton({
     return (
       <label
         {...(actionProps as LabelHTMLAttributes<HTMLLabelElement>)}
+        ref={ref as Ref<HTMLLabelElement>}
         title={title}
         className={actionClassName}
       >
@@ -71,12 +97,53 @@ export function PlatformIconButton({
     );
   }
 
+  if (asChild === 'spanButton') {
+    const {
+      disabled,
+      onClick,
+      onKeyDown,
+      tabIndex,
+      ...spanProps
+    } = actionProps as HTMLAttributes<HTMLSpanElement> & {
+      disabled?: boolean;
+    };
+    const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented || disabled) {
+        return;
+      }
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        event.currentTarget.click();
+      }
+    };
+
+    return (
+      <span
+        {...spanProps}
+        ref={ref as Ref<HTMLSpanElement>}
+        aria-disabled={disabled}
+        aria-label={label}
+        className={actionClassName}
+        onClick={disabled ? undefined : onClick}
+        onKeyDown={handleKeyDown}
+        role="button"
+        tabIndex={disabled ? -1 : (tabIndex ?? 0)}
+        title={title}
+      >
+        {icon}
+        {children}
+      </span>
+    );
+  }
+
   const { type = 'button', ...buttonProps } =
     actionProps as ButtonHTMLAttributes<HTMLButtonElement>;
 
   return (
     <button
       {...buttonProps}
+      ref={ref as Ref<HTMLButtonElement>}
       type={type}
       aria-label={label}
       title={title}
@@ -86,4 +153,4 @@ export function PlatformIconButton({
       {children}
     </button>
   );
-}
+});
diff --git a/src/components/common/PlatformInlineOptionButton.test.tsx b/src/components/common/PlatformInlineOptionButton.test.tsx
new file mode 100644
index 000000000..ec136ac29
--- /dev/null
+++ b/src/components/common/PlatformInlineOptionButton.test.tsx
@@ -0,0 +1,46 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { ChevronDown } from 'lucide-react';
+import { expect, test, vi } from 'vitest';
+
+import { PlatformInlineOptionButton } from './PlatformInlineOptionButton';
+
+test('renders shared inline option button chrome', () => {
+  const onClick = vi.fn();
+  render(
+    <PlatformInlineOptionButton
+      aria-label="生成比例 1:1"
+      className="local-option"
+      trailingIcon={<ChevronDown className="h-3 w-3" />}
+      onClick={onClick}
+    >
+      1:1
+    </PlatformInlineOptionButton>,
+  );
+
+  const button = screen.getByRole('button', { name: '生成比例 1:1' });
+
+  expect(button.className).toContain('platform-inline-option-button');
+  expect(button.className).toContain('bg-transparent');
+  expect(button.className).toContain('local-option');
+  expect(button.textContent).toContain('1:1');
+
+  fireEvent.click(button);
+
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+
+test('keeps disabled state and default button type', () => {
+  render(
+    <PlatformInlineOptionButton aria-label="模型" disabled>
+      GPT Image
+    </PlatformInlineOptionButton>,
+  );
+
+  const button = screen.getByRole('button', { name: '模型' });
+
+  expect(button.getAttribute('type')).toBe('button');
+  expect(button).toHaveProperty('disabled', true);
+  expect(button.className).toContain('disabled:cursor-not-allowed');
+});
diff --git a/src/components/common/PlatformInlineOptionButton.tsx b/src/components/common/PlatformInlineOptionButton.tsx
new file mode 100644
index 000000000..bc349d4e2
--- /dev/null
+++ b/src/components/common/PlatformInlineOptionButton.tsx
@@ -0,0 +1,39 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+
+type PlatformInlineOptionButtonProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'children'
+> & {
+  children: ReactNode;
+  trailingIcon?: ReactNode;
+};
+
+/**
+ * 平台内联选项按钮。
+ * 统一承接工具面板里“当前选项 + 下拉箭头”这类轻量 pill 动作。
+ */
+export const PlatformInlineOptionButton = forwardRef<
+  HTMLButtonElement,
+  PlatformInlineOptionButtonProps
+>(function PlatformInlineOptionButton(
+  { children, trailingIcon, className, type = 'button', ...buttonProps },
+  ref,
+) {
+  const actionClassName = [
+    'platform-inline-option-button inline-flex items-center justify-center border-0 bg-transparent text-sm font-black text-slate-700 transition-colors hover:text-slate-950 disabled:cursor-not-allowed disabled:opacity-55',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <button {...buttonProps} ref={ref} type={type} className={actionClassName}>
+      <span className="platform-inline-option-button__label">{children}</span>
+      {trailingIcon ? (
+        <span className="platform-inline-option-button__trailing" aria-hidden="true">
+          {trailingIcon}
+        </span>
+      ) : null}
+    </button>
+  );
+});
diff --git a/src/components/creation-home/CreationLandingView.test.tsx b/src/components/creation-home/CreationLandingView.test.tsx
new file mode 100644
index 000000000..ce026690d
--- /dev/null
+++ b/src/components/creation-home/CreationLandingView.test.tsx
@@ -0,0 +1,434 @@
+/* @vitest-environment jsdom */
+
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ContextType } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { AuthUiContext } from '../auth/AuthUiContext';
+import type { PlatformPublicGalleryCard } from '../rpg-entry/rpgEntryWorldPresentation';
+import { CreationLandingView } from './CreationLandingView';
+
+const listEditorProjectsMock = vi.hoisted(() => vi.fn());
+const createEditorProjectMock = vi.hoisted(() => vi.fn());
+const loadEditorAssetLibraryMock = vi.hoisted(() => vi.fn());
+
+type AuthValue = NonNullable<ContextType<typeof AuthUiContext>>;
+
+function createAuthValue(overrides: Partial<AuthValue> = {}): AuthValue {
+  return {
+    user: {
+      id: 'user-1',
+      publicUserCode: '100001',
+      displayName: '测试玩家',
+      avatarUrl: null,
+      phoneNumberMasked: null,
+      loginMethod: 'password',
+      bindingStatus: 'active',
+      wechatBound: false,
+    },
+    canAccessProtectedData: true,
+    openLoginModal: vi.fn(),
+    requireAuth: vi.fn((action: () => void) => action()),
+    openSettingsModal: vi.fn(),
+    openAccountModal: vi.fn(),
+    setCurrentUser: vi.fn(),
+    logout: vi.fn(),
+    musicVolume: 0.5,
+    setMusicVolume: vi.fn(),
+    platformTheme: 'light',
+    setPlatformTheme: vi.fn(),
+    isHydratingSettings: false,
+    isPersistingSettings: false,
+    settingsError: null,
+    ...overrides,
+  };
+}
+
+vi.mock('../../services/image-editor/editorProjectClient', () => ({
+  listEditorProjects: listEditorProjectsMock,
+  createEditorProject: createEditorProjectMock,
+  loadEditorAssetLibrary: loadEditorAssetLibraryMock,
+}));
+
+const projectItems = [
+  {
+    projectId: 'project-newest',
+    title: '最新项目',
+    viewport: { x: 0, y: 0, scale: 1 },
+    layers: [],
+    resources: [],
+    updatedAt: '2026-06-18T10:00:00.000Z',
+  },
+  {
+    projectId: 'project-old',
+    title: '旧项目',
+    viewport: { x: 0, y: 0, scale: 1 },
+    layers: [],
+    resources: [],
+    updatedAt: '2026-06-17T10:00:00.000Z',
+  },
+];
+
+type RenderCreationLandingOptions = {
+  authValue?: AuthValue | null;
+  publicGalleryEntries?: PlatformPublicGalleryCard[];
+};
+
+function renderCreationLanding({
+  authValue = createAuthValue(),
+  publicGalleryEntries = [],
+}: RenderCreationLandingOptions = {}) {
+  const result = render(
+    <AuthUiContext.Provider value={authValue}>
+      <CreationLandingView
+        onOpenProject={vi.fn()}
+        onOpenProjects={vi.fn()}
+        onOpenCommunity={vi.fn()}
+        publicGalleryEntries={publicGalleryEntries}
+      />
+    </AuthUiContext.Provider>,
+  );
+
+  return result;
+}
+
+describe('CreationLandingView', () => {
+  afterEach(() => {
+    listEditorProjectsMock.mockReset();
+    createEditorProjectMock.mockReset();
+    loadEditorAssetLibraryMock.mockReset();
+  });
+
+  it('renders the Taonier creation landing modules without external branding', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({ folders: [], assets: [] });
+
+    renderCreationLanding();
+
+    expect(
+      screen.getByRole('main', { name: '陶泥儿创作主页' }),
+    ).toBeTruthy();
+    expect(
+      screen.getByRole('heading', {
+        name: '陶泥儿 - 开启全民精品游戏创作',
+      }),
+    ).toBeTruthy();
+    expect(screen.getByText('登录即送100泥点，可以免费制作50个素材')).toBeTruthy();
+    expect(screen.getByRole('heading', { name: '创作工具' })).toBeTruthy();
+    expect(screen.getByText('游戏视觉规范')).toBeTruthy();
+    expect(screen.getByRole('heading', { name: '陶泥儿精选' })).toBeTruthy();
+    expect(screen.getByRole('tab', { name: '素材包' })).toBeTruthy();
+    expect(screen.queryByText('精选入口')).toBeNull();
+    expect(screen.queryByText(/Meowa|Discord/u)).toBeNull();
+    expect(await screen.findByText('暂无素材')).toBeTruthy();
+  });
+
+  it('shows recent projects only for logged in users', async () => {
+    const user = userEvent.setup();
+    const onOpenProject = vi.fn();
+    const onOpenProjects = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({ folders: [], assets: [] });
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue()}>
+        <CreationLandingView
+          onOpenProject={onOpenProject}
+          onOpenProjects={onOpenProjects}
+        />
+      </AuthUiContext.Provider>,
+    );
+
+    expect(await screen.findByRole('heading', { name: '最近项目' })).toBeTruthy();
+    expect(screen.getByText('最新项目')).toBeTruthy();
+    expect(screen.getByText('旧项目')).toBeTruthy();
+    await user.click(screen.getByRole('button', { name: '查看全部' }));
+    await user.click(screen.getByRole('button', { name: /最新项目/u }));
+
+    expect(onOpenProjects).toHaveBeenCalledTimes(1);
+    expect(onOpenProject).toHaveBeenCalledWith('project-newest');
+  });
+
+  it('hides recent projects and opens login when an anonymous user starts creation', async () => {
+    const user = userEvent.setup();
+    const openLoginModal = vi.fn();
+
+    renderCreationLanding({
+      authValue: createAuthValue({
+        user: null,
+        canAccessProtectedData: false,
+        openLoginModal,
+      }),
+    });
+
+    expect(screen.queryByRole('heading', { name: '最近项目' })).toBeNull();
+    await user.click(screen.getByRole('button', { name: /开始创作/u }));
+
+    expect(openLoginModal).toHaveBeenCalledWith(expect.any(Function));
+    expect(createEditorProjectMock).not.toHaveBeenCalled();
+  });
+
+  it('creates a new project and opens it from the hero action', async () => {
+    const user = userEvent.setup();
+    const onOpenProject = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({ folders: [], assets: [] });
+    createEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'created-project',
+      title: '未命名画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-18T10:00:00.000Z',
+    });
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue()}>
+        <CreationLandingView
+          onOpenProject={onOpenProject}
+          onOpenProjects={vi.fn()}
+        />
+      </AuthUiContext.Provider>,
+    );
+
+    await user.click(screen.getByRole('button', { name: /开始创作/u }));
+
+    await waitFor(() => {
+      expect(onOpenProject).toHaveBeenCalledWith('created-project');
+    });
+  });
+
+  it('opens the community entry from the hero without starting project creation', async () => {
+    const user = userEvent.setup();
+    const onOpenCommunity = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({ folders: [], assets: [] });
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue()}>
+        <CreationLandingView
+          onOpenProject={vi.fn()}
+          onOpenProjects={vi.fn()}
+          onOpenCommunity={onOpenCommunity}
+        />
+      </AuthUiContext.Provider>,
+    );
+
+    await user.click(screen.getByRole('button', { name: '玩家社区' }));
+
+    expect(onOpenCommunity).toHaveBeenCalledTimes(1);
+    expect(createEditorProjectMock).not.toHaveBeenCalled();
+  });
+
+  it('renders real account assets in showcase tabs without mock rows', async () => {
+    const user = userEvent.setup();
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [],
+      assets: [
+        {
+          assetId: 'asset-character',
+          folderId: 'folder-1',
+          label: '角色英雄',
+          imageSrc: 'data:image/png;base64,character',
+          width: 512,
+          height: 512,
+          sourceType: 'generated',
+          prompt: 'character hero prompt',
+          actualPrompt: null,
+          model: 'character-model',
+          provider: 'provider',
+          taskId: 'task-1',
+          authorName: '创作者A',
+          priceMudPoints: 20,
+        },
+      ],
+    });
+
+    renderCreationLanding();
+
+    await user.click(screen.getByRole('tab', { name: '角色' }));
+
+    const assetCard = await screen.findByText('角色英雄');
+    const card = assetCard.closest('.creation-landing__asset-card');
+    expect(card).toBeTruthy();
+    expect(within(card as HTMLElement).getByText('character hero prompt')).toBeTruthy();
+    expect(within(card as HTMLElement).getByText('创作者A')).toBeTruthy();
+    expect(within(card as HTMLElement).getByText('20泥点')).toBeTruthy();
+  });
+
+  it('opens a fullscreen asset preview modal with thumbnail navigation', async () => {
+    const user = userEvent.setup();
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [],
+      assets: [
+        {
+          assetId: 'asset-character',
+          folderId: 'folder-1',
+          label: '角色英雄',
+          imageSrc: 'data:image/png;base64,character',
+          width: 512,
+          height: 512,
+          sourceType: 'generated',
+          prompt: 'character hero prompt',
+          actualPrompt: null,
+          model: 'character-model',
+          provider: 'provider',
+          taskId: 'task-1',
+          assetKind: 'character',
+          authorName: '创作者A',
+          priceMudPoints: 20,
+        },
+        {
+          assetId: 'asset-animation',
+          folderId: 'folder-1',
+          label: '待机动画',
+          imageSrc: 'data:image/png;base64,animation',
+          width: 512,
+          height: 512,
+          sourceType: 'generated',
+          prompt: 'idle animation prompt',
+          actualPrompt: null,
+          model: 'seedance2.0-fast',
+          provider: 'ark',
+          taskId: 'task-2',
+          assetKind: 'character-animation',
+          priceMudPoints: 40,
+          generationInputs: {
+            fields: [{ title: '动作描述', value: '待机动作' }],
+            references: [
+              {
+                title: '角色图片',
+                label: '角色英雄',
+                refType: 'asset',
+                refId: 'asset-character',
+              },
+            ],
+          },
+        },
+      ],
+    });
+
+    renderCreationLanding();
+
+    await user.click(screen.getByRole('tab', { name: '角色' }));
+    await user.click(await screen.findByText('角色英雄'));
+
+    const dialog = await screen.findByRole('dialog', { name: '角色英雄' });
+    expect(within(dialog).getByText('生成总成本')).toBeTruthy();
+    expect(within(dialog).getByText('60泥点')).toBeTruthy();
+    expect(within(dialog).getByText('创作者A')).toBeTruthy();
+    expect(
+      within(dialog).getByLabelText('素材缩略图导航'),
+    ).toBeTruthy();
+
+    await user.click(within(dialog).getByRole('button', { name: '查看待机动画' }));
+    expect(
+      within(dialog).getByRole('button', { name: '查看待机动画' }).getAttribute(
+        'aria-current',
+      ),
+    ).toBe('true');
+  });
+
+  it('uses Taonier featured as the account asset waterfall instead of creation entries', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [],
+      assets: [
+        {
+          assetId: 'asset-pack-a',
+          folderId: 'folder-1',
+          label: '素材包 A',
+          imageSrc: 'data:image/png;base64,a',
+          width: 512,
+          height: 640,
+          sourceType: 'generated',
+          prompt: '素材包提示词',
+          actualPrompt: null,
+          model: null,
+          provider: null,
+          taskId: null,
+        },
+        {
+          assetId: 'asset-pack-b',
+          folderId: 'folder-1',
+          label: '素材包 B',
+          imageSrc: 'data:image/png;base64,b',
+          width: 512,
+          height: 512,
+          sourceType: 'generated',
+          prompt: '第二组素材',
+          actualPrompt: null,
+          model: null,
+          provider: null,
+          taskId: null,
+        },
+      ],
+    });
+
+    const { container } = renderCreationLanding();
+
+    expect(await screen.findByText('素材包 A')).toBeTruthy();
+    expect(screen.getByText('素材包 B')).toBeTruthy();
+    expect(
+      screen.getByLabelText('用户素材瀑布流').className,
+    ).toContain('creation-landing__asset-waterfall');
+    const firstPreview = container.querySelector(
+      '.creation-landing__asset-preview',
+    ) as HTMLElement | null;
+    expect(firstPreview?.style.aspectRatio).toBe('512 / 640');
+    expect(screen.queryByText('经典 RPG 体验')).toBeNull();
+    expect(screen.queryByText('拼图关卡创作')).toBeNull();
+  });
+
+  it('falls back to real public user assets for the featured waterfall', async () => {
+    const publicAsset = {
+      sourceType: 'puzzle',
+      workId: 'work-public-asset',
+      profileId: 'profile-public-asset',
+      publicWorkCode: 'PZ-PUBLIC-ASSET',
+      ownerUserId: 'owner-public-asset',
+      authorDisplayName: '公开作者',
+      worldName: '公开素材组合',
+      subtitle: '公开素材副标题',
+      summaryText: '公开用户生成素材提示词',
+      coverImageSrc: 'https://assets.example.test/public-asset.png',
+      coverSlides: [
+        {
+          id: 'slide-1',
+          imageSrc: 'https://assets.example.test/public-asset-slide.png',
+          label: '公开素材图',
+        },
+      ],
+      themeTags: ['素材包'],
+      visibility: 'published',
+      publishedAt: '2026-06-18T09:00:00.000Z',
+      updatedAt: '2026-06-18T10:00:00.000Z',
+    } satisfies PlatformPublicGalleryCard;
+
+    const { container } = renderCreationLanding({
+      authValue: createAuthValue({
+        user: null,
+        canAccessProtectedData: false,
+      }),
+      publicGalleryEntries: [publicAsset],
+    });
+
+    expect(await screen.findByText('公开素材组合')).toBeTruthy();
+    const card = screen
+      .getByText('公开素材组合')
+      .closest('.creation-landing__asset-card');
+    expect(card).toBeTruthy();
+    expect(
+      within(card as HTMLElement).getByText('公开用户生成素材提示词'),
+    ).toBeTruthy();
+    expect(within(card as HTMLElement).getByText('公开作者')).toBeTruthy();
+    expect(
+      container.querySelector('.creation-landing__asset-waterfall'),
+    ).toBeTruthy();
+    expect(screen.queryByText('暂无素材')).toBeNull();
+    expect(screen.queryByText('精选入口')).toBeNull();
+  });
+});
diff --git a/src/components/creation-home/CreationLandingView.tsx b/src/components/creation-home/CreationLandingView.tsx
new file mode 100644
index 000000000..23c79b9f0
--- /dev/null
+++ b/src/components/creation-home/CreationLandingView.tsx
@@ -0,0 +1,722 @@
+import { Film, Image as ImageIcon, Music2 } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import {
+  createEditorProject,
+  listEditorProjects,
+  loadEditorAssetLibrary,
+  type EditorAssetLibrarySnapshot,
+  type EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import { ApiClientError } from '../../services/apiClient';
+import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
+import { useAuthUi } from '../auth/AuthUiContext';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
+import { PlatformModalCloseButton } from '../common/PlatformModalCloseButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { UnifiedModal } from '../common/UnifiedModal';
+import { ProjectCanvasCover } from '../project/ProjectCanvasCover';
+import { ResolvedAssetImage } from '../ResolvedAssetImage';
+import { ResolvedAssetVideo } from '../ResolvedAssetVideo';
+import type { PlatformPublicGalleryCard } from '../rpg-entry/rpgEntryWorldPresentation';
+import {
+  buildCreationShowcaseItems,
+  SHOWCASE_TABS,
+  type ShowcaseAssetItem,
+  type ShowcaseAssetPreview,
+  type ShowcaseTabId,
+} from './creationShowcaseModel';
+
+type CreationLandingViewProps = {
+  onOpenProject: (projectId: string) => void;
+  onOpenProjects: () => void;
+  onOpenCommunity?: () => void;
+  publicGalleryEntries?: PlatformPublicGalleryCard[];
+};
+
+type CreationFeatureItem = {
+  title: string;
+  description: string;
+  iconSrc: string;
+};
+
+const CREATION_HOME_ASSETS = {
+  heroCreate: '/creation-home/hero-create.png',
+  heroCommunity: '/creation-home/hero-community.png',
+  projectNew: '/creation-home/project-new.png',
+} as const;
+
+const CREATION_FEATURES: CreationFeatureItem[] = [
+  {
+    title: '游戏视觉规范',
+    description: '轻松约束多类素材视觉一致性',
+    iconSrc: '/creation-home/feature-visual-spec.png',
+  },
+  {
+    title: '游戏角色',
+    description: '整套高完成度2D/3D角色素材及动画',
+    iconSrc: '/creation-home/feature-character.png',
+  },
+  {
+    title: '游戏UI',
+    description: '轻松生成高一致性的UI素材',
+    iconSrc: '/creation-home/feature-ui.png',
+  },
+  {
+    title: '游戏音乐',
+    description: '轻松制作游戏背景音乐、音效',
+    iconSrc: '/creation-home/feature-music.png',
+  },
+  {
+    title: '游戏特效',
+    description: '低成本生成精品游戏特效',
+    iconSrc: '/creation-home/feature-effects.png',
+  },
+  {
+    title: '游戏场景',
+    description: '轻松生成各类游戏场景素材',
+    iconSrc: '/creation-home/feature-scene.png',
+  },
+  {
+    title: '游戏美宣',
+    description: '轻松生成游戏上架所需图片和视频',
+    iconSrc: '/creation-home/feature-marketing.png',
+  },
+  {
+    title: '游戏功能编码',
+    description: '自然语言驱动游戏生成',
+    iconSrc: '/creation-home/feature-coding.png',
+  },
+  {
+    title: '一键导出',
+    description: '支持导出为微抖小游戏、Godot、Unity、UE工程',
+    iconSrc: '/creation-home/feature-export.png',
+  },
+];
+
+function isUnauthorizedError(error: unknown) {
+  return error instanceof ApiClientError && error.status === 401;
+}
+
+function formatProjectUpdatedAt(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+  return new Intl.DateTimeFormat('zh-CN', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+}
+
+function getPreviewAspectRatio(preview: ShowcaseAssetPreview) {
+  return preview.width && preview.height
+    ? `${Math.max(1, preview.width)} / ${Math.max(1, preview.height)}`
+    : undefined;
+}
+
+function getPreviewIcon(preview: ShowcaseAssetPreview) {
+  if (preview.mediaType === 'audio') {
+    return <Music2 aria-hidden="true" />;
+  }
+  if (preview.mediaType === 'video') {
+    return <Film aria-hidden="true" />;
+  }
+  return <ImageIcon aria-hidden="true" />;
+}
+
+function ShowcaseAudioPreview({
+  preview,
+  controls = false,
+}: {
+  preview: ShowcaseAssetPreview;
+  controls?: boolean;
+}) {
+  const { resolvedUrl } = useResolvedAssetReadUrl(preview.src, {
+    objectKey: preview.objectKey,
+  });
+
+  return (
+    <div className="creation-landing__asset-audio-preview">
+      <Music2 aria-hidden="true" />
+      {controls && resolvedUrl ? (
+        <audio controls preload="metadata" src={resolvedUrl} />
+      ) : null}
+    </div>
+  );
+}
+
+function ShowcasePreview({
+  preview,
+  variant = 'card',
+}: {
+  preview: ShowcaseAssetPreview;
+  variant?: 'card' | 'modal' | 'thumb';
+}) {
+  if (preview.mediaType === 'audio') {
+    return (
+      <ShowcaseAudioPreview preview={preview} controls={variant === 'modal'} />
+    );
+  }
+  if (preview.mediaType === 'video') {
+    return (
+      <ShowcaseVideoPreview
+        preview={preview}
+        controls={variant === 'modal'}
+        variant={variant}
+      />
+    );
+  }
+  return <ShowcaseImagePreview preview={preview} variant={variant} />;
+}
+
+function ShowcaseImagePreview({
+  preview,
+  variant,
+}: {
+  preview: ShowcaseAssetPreview;
+  variant: 'card' | 'modal' | 'thumb';
+}) {
+  return (
+    <ResolvedAssetImage
+      src={preview.src}
+      objectKey={preview.objectKey}
+      alt={preview.label}
+      className={
+        variant === 'modal'
+          ? 'creation-landing__showcase-media'
+          : 'h-full w-full object-contain'
+      }
+    />
+  );
+}
+
+function ShowcaseVideoPreview({
+  preview,
+  controls,
+  variant,
+}: {
+  preview: ShowcaseAssetPreview;
+  controls: boolean;
+  variant: 'card' | 'modal' | 'thumb';
+}) {
+  return (
+    <ResolvedAssetVideo
+      src={preview.src}
+      objectKey={preview.objectKey}
+      className={
+        variant === 'modal'
+          ? 'creation-landing__showcase-media'
+          : 'h-full w-full object-contain'
+      }
+      controls={controls}
+      muted={!controls}
+      loop={!controls}
+      playsInline
+    />
+  );
+}
+
+function ShowcaseBundlePreview({
+  item,
+}: {
+  item: ShowcaseAssetItem;
+}) {
+  const visiblePreviews = item.previews.slice(0, 4);
+  const primaryPreview = visiblePreviews[0];
+
+  if (!primaryPreview) {
+    return null;
+  }
+
+  return (
+    <div
+      className={
+        item.previews.length > 1
+          ? 'creation-landing__asset-preview creation-landing__asset-preview--bundle'
+          : 'creation-landing__asset-preview'
+      }
+      style={{
+        aspectRatio: getPreviewAspectRatio(primaryPreview),
+      }}
+    >
+      {visiblePreviews.map((preview) => (
+        <span
+          key={preview.id}
+          className="creation-landing__asset-preview-tile"
+          aria-label={preview.label}
+        >
+          <ShowcasePreview preview={preview} />
+        </span>
+      ))}
+      {item.previews.length > visiblePreviews.length ? (
+        <span className="creation-landing__asset-preview-more">
+          +{item.previews.length - visiblePreviews.length}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+function CreationShowcaseModal({
+  item,
+  activeIndex,
+  onSelectIndex,
+  onClose,
+}: {
+  item: ShowcaseAssetItem | null;
+  activeIndex: number;
+  onSelectIndex: (index: number) => void;
+  onClose: () => void;
+}) {
+  const safeActiveIndex = item
+    ? Math.min(Math.max(activeIndex, 0), item.previews.length - 1)
+    : 0;
+  const activePreview = item?.previews[safeActiveIndex] ?? null;
+
+  return (
+    <UnifiedModal
+      open={Boolean(item && activePreview)}
+      title={item?.label ?? '素材预览'}
+      ariaLabel={item?.label ?? '素材预览'}
+      onClose={onClose}
+      showHeader={false}
+      showCloseButton={false}
+      size="fullscreen"
+      zIndexClassName="z-[120]"
+      overlayClassName="creation-landing__showcase-modal-overlay"
+      panelClassName="creation-landing__showcase-modal-panel"
+      bodyClassName="creation-landing__showcase-modal-body"
+      closeOnBackdrop
+    >
+      {item && activePreview ? (
+        <div className="creation-landing__showcase-modal">
+          <PlatformModalCloseButton
+            label="关闭素材预览"
+            variant="floating"
+            className="creation-landing__showcase-modal-close"
+            onClick={onClose}
+          />
+          <div className="creation-landing__showcase-modal-stage">
+            <div className="creation-landing__showcase-current">
+              <ShowcasePreview preview={activePreview} variant="modal" />
+            </div>
+          </div>
+          <div className="creation-landing__showcase-dock">
+            <div className="creation-landing__showcase-dock-meta">
+              <h3>{item.label}</h3>
+              <p>{item.prompt}</p>
+              <dl>
+                <div>
+                  <dt>作者</dt>
+                  <dd>{item.author}</dd>
+                </div>
+                <div>
+                  <dt>生成总成本</dt>
+                  <dd>{item.cost}</dd>
+                </div>
+              </dl>
+            </div>
+            <div
+              className="creation-landing__showcase-thumbs"
+              aria-label="素材缩略图导航"
+            >
+              {item.previews.map((preview, index) => (
+                <button
+                  key={preview.id}
+                  type="button"
+                  className={
+                    index === safeActiveIndex
+                      ? 'creation-landing__showcase-thumb creation-landing__showcase-thumb--active'
+                      : 'creation-landing__showcase-thumb'
+                  }
+                  aria-label={`查看${preview.label}`}
+                  aria-current={index === safeActiveIndex ? 'true' : undefined}
+                  onClick={() => onSelectIndex(index)}
+                >
+                  <span className="creation-landing__showcase-thumb-media">
+                    {preview.mediaType === 'image' ? (
+                      <ShowcasePreview preview={preview} variant="thumb" />
+                    ) : (
+                      getPreviewIcon(preview)
+                    )}
+                  </span>
+                  <span>{preview.label}</span>
+                </button>
+              ))}
+            </div>
+          </div>
+        </div>
+      ) : null}
+    </UnifiedModal>
+  );
+}
+
+export function CreationLandingView({
+  onOpenProject,
+  onOpenProjects,
+  onOpenCommunity,
+  publicGalleryEntries = [],
+}: CreationLandingViewProps) {
+  const authUi = useAuthUi();
+  const isAuthenticated = Boolean(authUi?.user);
+  const [recentProjects, setRecentProjects] = useState<EditorProjectSnapshot[]>(
+    [],
+  );
+  const [isLoadingProjects, setIsLoadingProjects] = useState(false);
+  const [isCreatingProject, setIsCreatingProject] = useState(false);
+  const [projectError, setProjectError] = useState<string | null>(null);
+  const [assetLibrary, setAssetLibrary] =
+    useState<EditorAssetLibrarySnapshot | null>(null);
+  const [isLoadingAssets, setIsLoadingAssets] = useState(false);
+  const [assetError, setAssetError] = useState<string | null>(null);
+  const [activeShowcaseTab, setActiveShowcaseTab] =
+    useState<ShowcaseTabId>('packs');
+  const [selectedShowcaseItem, setSelectedShowcaseItem] =
+    useState<ShowcaseAssetItem | null>(null);
+  const [selectedShowcaseIndex, setSelectedShowcaseIndex] = useState(0);
+
+  const refreshRecentProjects = useCallback(() => {
+    if (!isAuthenticated) {
+      setRecentProjects([]);
+      setProjectError(null);
+      return;
+    }
+    setIsLoadingProjects(true);
+    setProjectError(null);
+    listEditorProjects()
+      .then((projects) => {
+        setRecentProjects(
+          [...projects]
+            .sort(
+              (left, right) =>
+                new Date(right.updatedAt).getTime() -
+                new Date(left.updatedAt).getTime(),
+            )
+            .slice(0, 4),
+        );
+      })
+      .catch((error: unknown) => {
+        if (isUnauthorizedError(error)) {
+          authUi?.openLoginModal(refreshRecentProjects);
+          return;
+        }
+        setProjectError(
+          error instanceof Error ? error.message : '读取最近项目失败',
+        );
+      })
+      .finally(() => setIsLoadingProjects(false));
+  }, [authUi, isAuthenticated]);
+
+  const refreshAssetLibrary = useCallback(() => {
+    if (!isAuthenticated) {
+      setAssetLibrary(null);
+      setAssetError(null);
+      return;
+    }
+    setIsLoadingAssets(true);
+    setAssetError(null);
+    loadEditorAssetLibrary()
+      .then(setAssetLibrary)
+      .catch((error: unknown) => {
+        if (isUnauthorizedError(error)) {
+          return;
+        }
+        setAssetError(
+          error instanceof Error ? error.message : '读取素材展示失败',
+        );
+      })
+      .finally(() => setIsLoadingAssets(false));
+  }, [isAuthenticated]);
+
+  useEffect(() => {
+    refreshRecentProjects();
+  }, [refreshRecentProjects]);
+
+  useEffect(() => {
+    refreshAssetLibrary();
+  }, [refreshAssetLibrary]);
+
+  const createProject = useCallback(() => {
+    if (authUi && !authUi.user) {
+      authUi.openLoginModal(createProject);
+      return;
+    }
+    setIsCreatingProject(true);
+    setProjectError(null);
+    createEditorProject()
+      .then((project) => onOpenProject(project.projectId))
+      .catch((error: unknown) => {
+        if (isUnauthorizedError(error)) {
+          authUi?.openLoginModal(createProject);
+          return;
+        }
+        setProjectError(
+          error instanceof Error ? error.message : '创建项目失败',
+        );
+      })
+      .finally(() => setIsCreatingProject(false));
+  }, [authUi, onOpenProject]);
+
+  const showcaseItems = useMemo(
+    () =>
+      buildCreationShowcaseItems({
+        activeTab: activeShowcaseTab,
+        assetLibrary,
+        publicGalleryEntries,
+        fallbackAuthorName: authUi?.user?.displayName,
+      }),
+    [activeShowcaseTab, assetLibrary, authUi?.user?.displayName, publicGalleryEntries],
+  );
+
+  const isShowcaseLoading = isAuthenticated && isLoadingAssets;
+  const showcaseEmptyText =
+    publicGalleryEntries.length > 0 ? '暂无匹配素材' : '暂无素材';
+
+  const renderAssetShowcase = () => {
+    if (assetError) {
+      return (
+        <PlatformStatusMessage tone="error" surface="platform" role="alert">
+          {assetError}
+        </PlatformStatusMessage>
+      );
+    }
+    if (isShowcaseLoading) {
+      return (
+        <PlatformEmptyState surface="subpanel" size="inline">
+          正在读取素材
+        </PlatformEmptyState>
+      );
+    }
+    if (showcaseItems.length === 0) {
+      return (
+        <PlatformEmptyState surface="subpanel" size="inline">
+          {showcaseEmptyText}
+        </PlatformEmptyState>
+      );
+    }
+
+    return (
+      <div className="creation-landing__asset-waterfall" aria-label="用户素材瀑布流">
+        {showcaseItems.map((item) => (
+          <button
+            key={item.id}
+            type="button"
+            className="creation-landing__asset-card"
+            onClick={() => {
+              setSelectedShowcaseItem(item);
+              setSelectedShowcaseIndex(0);
+            }}
+          >
+            <ShowcaseBundlePreview item={item} />
+            <div className="creation-landing__asset-meta">
+              <h3>{item.label}</h3>
+              <p>{item.prompt}</p>
+              <dl>
+                <div>
+                  <dt>作者</dt>
+                  <dd>{item.author}</dd>
+                </div>
+                <div>
+                  <dt>生成总成本</dt>
+                  <dd>{item.cost}</dd>
+                </div>
+              </dl>
+            </div>
+          </button>
+        ))}
+      </div>
+    );
+  };
+
+  return (
+    <main className="creation-landing" aria-label="陶泥儿创作主页">
+      <section className="creation-landing__hero">
+        <div className="creation-landing__hero-copy">
+          <span className="creation-landing__eyebrow">陶泥儿创作工具</span>
+          <h1>陶泥儿 - 开启全民精品游戏创作</h1>
+          <p>登录即送100泥点，可以免费制作50个素材</p>
+          <div className="creation-landing__hero-actions">
+            <PlatformActionButton
+              size="md"
+              shape="pill"
+              className="creation-landing__hero-action creation-landing__hero-action--primary"
+              onClick={createProject}
+              disabled={isCreatingProject}
+            >
+              <img
+                src={CREATION_HOME_ASSETS.heroCreate}
+                alt=""
+                aria-hidden="true"
+                draggable={false}
+                className="creation-landing__button-art"
+              />
+              开始创作
+            </PlatformActionButton>
+            {onOpenCommunity ? (
+              <PlatformActionButton
+                tone="secondary"
+                size="md"
+                shape="pill"
+                className="creation-landing__hero-action creation-landing__hero-action--secondary"
+                onClick={onOpenCommunity}
+              >
+                <img
+                  src={CREATION_HOME_ASSETS.heroCommunity}
+                  alt=""
+                  aria-hidden="true"
+                  draggable={false}
+                  className="creation-landing__button-art"
+                />
+                玩家社区
+              </PlatformActionButton>
+            ) : null}
+          </div>
+        </div>
+        <div className="creation-landing__hero-board" aria-hidden="true">
+          <span className="creation-landing__hero-tile creation-landing__hero-tile--main" />
+          <span className="creation-landing__hero-tile creation-landing__hero-tile--side" />
+          <span className="creation-landing__hero-tile creation-landing__hero-tile--small" />
+        </div>
+      </section>
+
+      <section className="creation-landing__section">
+        <div className="creation-landing__section-header">
+          <div>
+            <h2>创作工具</h2>
+          </div>
+        </div>
+        <div className="creation-landing__feature-grid">
+          {CREATION_FEATURES.map((feature) => (
+            <article key={feature.title} className="creation-landing__feature">
+              <span className="creation-landing__feature-figure">
+                <span className="creation-landing__feature-icon">
+                  <img
+                    src={feature.iconSrc}
+                    alt=""
+                    aria-hidden="true"
+                    loading="lazy"
+                    draggable={false}
+                    className="creation-landing__feature-art"
+                  />
+                </span>
+              </span>
+              <span className="creation-landing__feature-copy">
+                <h3>{feature.title}</h3>
+                <p>{feature.description}</p>
+              </span>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      {isAuthenticated ? (
+        <section className="creation-landing__section">
+          <div className="creation-landing__section-header">
+            <div>
+              <h2>最近项目</h2>
+            </div>
+            <button
+              type="button"
+              className="creation-landing__link-button"
+              onClick={onOpenProjects}
+            >
+              查看全部
+            </button>
+          </div>
+          {projectError ? (
+            <PlatformStatusMessage tone="error" surface="platform" role="alert">
+              {projectError}
+            </PlatformStatusMessage>
+          ) : null}
+          <div className="creation-landing__project-row">
+            <button
+              type="button"
+              className="creation-landing__project-card creation-landing__project-card--new"
+              onClick={createProject}
+              disabled={isCreatingProject}
+            >
+              <span>
+                <img
+                  src={CREATION_HOME_ASSETS.projectNew}
+                  alt=""
+                  aria-hidden="true"
+                  draggable={false}
+                  className="creation-landing__project-new-art"
+                />
+              </span>
+              新建项目
+            </button>
+            {isLoadingProjects ? (
+              <PlatformEmptyState surface="subpanel" size="inline">
+                正在读取项目
+              </PlatformEmptyState>
+            ) : (
+              recentProjects.map((project) => (
+                <button
+                  key={project.projectId}
+                  type="button"
+                  className="creation-landing__project-card"
+                  onClick={() => onOpenProject(project.projectId)}
+                >
+                  <PlatformMediaFrame
+                    src={null}
+                    alt=""
+                    fallbackLabel="项目"
+                    aspect="standard"
+                    surface="bright"
+                    className="creation-landing__project-cover"
+                    fallbackContent={<ProjectCanvasCover project={project} />}
+                  />
+                  <span className="creation-landing__project-meta">
+                    <strong>{project.title}</strong>
+                    <small>{formatProjectUpdatedAt(project.updatedAt)}</small>
+                  </span>
+                </button>
+              ))
+            )}
+          </div>
+        </section>
+      ) : null}
+
+      <section className="creation-landing__section">
+        <div className="creation-landing__section-header">
+          <div>
+            <h2>陶泥儿精选</h2>
+          </div>
+        </div>
+        <div className="creation-landing__tabs" role="tablist" aria-label="用户素材分类">
+          {SHOWCASE_TABS.map((tab) => (
+            <button
+              key={tab.id}
+              type="button"
+              role="tab"
+              aria-selected={activeShowcaseTab === tab.id}
+              className={
+                activeShowcaseTab === tab.id
+                  ? 'creation-landing__tab creation-landing__tab--active'
+                  : 'creation-landing__tab'
+              }
+              onClick={() => setActiveShowcaseTab(tab.id)}
+            >
+              {tab.label}
+            </button>
+          ))}
+        </div>
+        {renderAssetShowcase()}
+      </section>
+      <CreationShowcaseModal
+        item={selectedShowcaseItem}
+        activeIndex={selectedShowcaseIndex}
+        onSelectIndex={setSelectedShowcaseIndex}
+        onClose={() => setSelectedShowcaseItem(null)}
+      />
+    </main>
+  );
+}
+
+export default CreationLandingView;
diff --git a/src/components/creation-home/creationShowcaseModel.test.ts b/src/components/creation-home/creationShowcaseModel.test.ts
new file mode 100644
index 000000000..90ffd8089
--- /dev/null
+++ b/src/components/creation-home/creationShowcaseModel.test.ts
@@ -0,0 +1,358 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  EditorAssetLibrarySnapshot,
+  EditorAssetSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import { buildCreationShowcaseItems } from './creationShowcaseModel';
+
+function createAsset(
+  overrides: Partial<EditorAssetSnapshot> & Record<string, unknown>,
+): EditorAssetSnapshot {
+  return {
+    assetId: 'asset-1',
+    folderId: 'folder-1',
+    label: '素材',
+    imageSrc: 'data:image/png;base64,asset',
+    width: 512,
+    height: 512,
+    sourceType: 'generated',
+    prompt: null,
+    actualPrompt: null,
+    model: null,
+    provider: null,
+    taskId: null,
+    ...overrides,
+  };
+}
+
+function createLibrary(assets: EditorAssetSnapshot[]): EditorAssetLibrarySnapshot {
+  return {
+    folders: [],
+    assets,
+  };
+}
+
+describe('creationShowcaseModel', () => {
+  it('groups pack items by the same referenced spec image and sums known cost', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'packs',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'spec-1',
+          label: '角色规范图',
+          assetKind: 'spec',
+          prompt: '规范提示词',
+          priceMudPoints: 5,
+          authorName: '创作者A',
+        }),
+        createAsset({
+          assetId: 'character-1',
+          label: '角色主图',
+          assetKind: 'character',
+          priceMudPoints: 12,
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '角色提示词' }],
+            references: [
+              {
+                title: '角色规范',
+                label: '角色规范图',
+                refType: 'asset',
+                refId: 'spec-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.label).toBe('角色规范图');
+    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
+      '角色规范图',
+      '角色主图',
+    ]);
+    expect(items[0]?.prompt).toBe('规范提示词');
+    expect(items[0]?.author).toBe('创作者A');
+    expect(items[0]?.cost).toBe('17泥点');
+  });
+
+  it('groups assets when references point to the source project resource', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'packs',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'spec-1',
+          label: '项目规范图',
+          assetKind: 'spec',
+          sourceResourceId: 'resource-spec-1',
+        }),
+        createAsset({
+          assetId: 'character-1',
+          label: '项目角色图',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '项目角色提示词' }],
+            references: [
+              {
+                title: '角色规范',
+                label: '项目规范图',
+                refType: 'project-resource',
+                refId: 'resource-spec-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
+      '项目规范图',
+      '项目角色图',
+    ]);
+  });
+
+  it('groups character animations under the referenced character image', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'characters',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'character-1',
+          label: '游戏角色图',
+          assetKind: 'character',
+          prompt: '角色提示词',
+        }),
+        createAsset({
+          assetId: 'animation-1',
+          label: '待机动画',
+          assetKind: 'character-animation',
+          imageSrc: 'data:image/png;base64,animation',
+          generationInputs: {
+            fields: [{ title: '动作描述', value: '待机动作' }],
+            references: [
+              {
+                title: '角色图片',
+                label: '游戏角色图',
+                refType: 'asset',
+                refId: 'character-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.label).toBe('游戏角色图');
+    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
+      '游戏角色图',
+      '待机动画',
+    ]);
+  });
+
+  it('groups UI design extraction assets under the referenced UI image', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'ui',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'ui-design-1',
+          label: '游戏UI图',
+          assetKind: 'ui-design',
+          prompt: 'UI提示词',
+        }),
+        createAsset({
+          assetId: 'icon-sheet-1',
+          label: 'UI子素材图集',
+          assetKind: 'icon-spritesheet',
+          generationInputs: {
+            fields: [{ title: '提取提示词', value: '提取UI子素材' }],
+            references: [
+              {
+                title: 'UI设计图',
+                label: '游戏UI图',
+                refType: 'asset',
+                refId: 'ui-design-1',
+              },
+            ],
+          },
+        }),
+        createAsset({
+          assetId: 'icon-1',
+          label: '开始按钮',
+          assetKind: 'icon',
+          generationInputs: {
+            fields: [{ title: '提取提示词', value: '提取UI子素材' }],
+            references: [
+              {
+                title: 'UI设计图',
+                label: '游戏UI图',
+                refType: 'asset',
+                refId: 'ui-design-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.label).toBe('游戏UI图');
+    expect(items[0]?.previews.map((preview) => preview.label)).toEqual([
+      '游戏UI图',
+      'UI子素材图集',
+      '开始按钮',
+    ]);
+  });
+
+  it('counts a spritesheet task only once when UI children share the same task', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'ui',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'ui-design-1',
+          label: '游戏UI图',
+          assetKind: 'ui-design',
+          model: 'gemini-3.1-flash-image-preview',
+          taskId: 'task-ui-design',
+        }),
+        createAsset({
+          assetId: 'icon-sheet-1',
+          label: 'UI子素材图集',
+          assetKind: 'icon-spritesheet',
+          model: 'gpt-image-2',
+          taskId: 'task-ui-extract',
+          generationInputs: {
+            fields: [{ title: '提取提示词', value: '提取UI子素材' }],
+            references: [
+              {
+                title: 'UI设计图',
+                label: '游戏UI图',
+                refType: 'asset',
+                refId: 'ui-design-1',
+              },
+            ],
+          },
+        }),
+        createAsset({
+          assetId: 'icon-1',
+          label: '开始按钮',
+          assetKind: 'icon',
+          model: 'gpt-image-2',
+          taskId: 'task-ui-extract',
+          generationInputs: {
+            fields: [{ title: '提取提示词', value: '提取UI子素材' }],
+            references: [
+              {
+                title: 'UI设计图',
+                label: '游戏UI图',
+                refType: 'asset',
+                refId: 'ui-design-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.cost).toBe('32泥点');
+  });
+
+  it('keeps music assets as audio preview items', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'music',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'music-1',
+          label: '背景音乐',
+          imageSrc: '/generated-editor-audios/music.mp3',
+          assetKind: 'background-music',
+          prompt: '舒缓背景音乐',
+          priceMudPoints: '5',
+        }),
+      ]),
+      publicGalleryEntries: [],
+      fallbackAuthorName: '当前用户',
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.previews[0]?.mediaType).toBe('audio');
+    expect(items[0]?.author).toBe('当前用户');
+    expect(items[0]?.cost).toBe('5泥点');
+  });
+
+  it('keeps character animation videos out of the marketing tab', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'marketing',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'animation-1',
+          label: '角色动画',
+          assetKind: 'character-animation',
+          imageSrc: '/generated-editor-videos/animation.mp4',
+        }),
+        createAsset({
+          assetId: 'poster-1',
+          label: '上线美宣视频',
+          assetKind: 'publication-material',
+          imageSrc: '/generated-editor-videos/poster.mp4',
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.label).toBe('上线美宣视频');
+    expect(items[0]?.previews[0]?.mediaType).toBe('video');
+  });
+
+  it('infers costs from generated asset kinds when stored price is absent', () => {
+    const items = buildCreationShowcaseItems({
+      activeTab: 'characters',
+      assetLibrary: createLibrary([
+        createAsset({
+          assetId: 'character-1',
+          label: '游戏角色图',
+          imageSrc: '/generated-editor-assets/character.png',
+          objectKey: 'generated-editor-assets/character.png',
+          assetKind: 'character',
+          model: 'gpt-image-2',
+          prompt: '角色提示词',
+        }),
+        createAsset({
+          assetId: 'animation-1',
+          label: '待机动画',
+          assetKind: 'character-animation',
+          imageSrc: '/generated-editor-videos/animation.mp4',
+          objectKey: 'generated-editor-videos/animation.mp4',
+          model: 'seedance2.0-fast',
+          durationSeconds: 6,
+          generationInputs: {
+            fields: [{ title: '清晰度', value: '720p' }],
+            references: [
+              {
+                title: '角色图片',
+                label: '游戏角色图',
+                refType: 'asset',
+                refId: 'character-1',
+              },
+            ],
+          },
+        }),
+      ]),
+      publicGalleryEntries: [],
+    });
+
+    expect(items).toHaveLength(1);
+    expect(items[0]?.cost).toBe('140泥点');
+    expect(items[0]?.previews[0]?.objectKey).toBe(
+      'generated-editor-assets/character.png',
+    );
+  });
+});
diff --git a/src/components/creation-home/creationShowcaseModel.ts b/src/components/creation-home/creationShowcaseModel.ts
new file mode 100644
index 000000000..2e6f299c9
--- /dev/null
+++ b/src/components/creation-home/creationShowcaseModel.ts
@@ -0,0 +1,754 @@
+import type {
+  EditorAssetGenerationInputReference,
+  EditorAssetLibrarySnapshot,
+  EditorAssetSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import {
+  calculateCharacterAnimationPrice,
+  calculateEditorBackgroundMusicPrice,
+  calculateEditorImageGenerationPrice,
+  calculateEditorSoundEffectPrice,
+  calculateEditorVideoPrice,
+  CHARACTER_ANIMATION_MODEL,
+  DEFAULT_BACKGROUND_MUSIC_MODEL,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  DEFAULT_VIDEO_DURATION_SECONDS,
+  DEFAULT_VIDEO_MODEL,
+} from '../image-editor/ImageCanvasGenerationModel';
+import {
+  resolvePlatformWorkAuthorDisplayName,
+  resolvePlatformWorldCoverImage,
+  resolvePlatformWorldCoverSlides,
+  type PlatformPublicGalleryCard,
+} from '../rpg-entry/rpgEntryWorldPresentation';
+
+export type ShowcaseTabId =
+  | 'packs'
+  | 'characters'
+  | 'ui'
+  | 'music'
+  | 'effects'
+  | 'scenes'
+  | 'marketing'
+  | 'games';
+
+export type ShowcaseAssetMediaType = 'image' | 'video' | 'audio';
+
+export type ShowcaseAssetPreview = {
+  id: string;
+  label: string;
+  src: string;
+  objectKey?: string | null;
+  mediaType: ShowcaseAssetMediaType;
+  width?: number;
+  height?: number;
+};
+
+export type ShowcaseAssetItem = {
+  id: string;
+  label: string;
+  previews: ShowcaseAssetPreview[];
+  prompt: string;
+  author: string;
+  cost: string;
+};
+
+type ShowcaseAssetGroup = {
+  id: string;
+  label?: string;
+  assets: EditorAssetSnapshot[];
+};
+
+const UNKNOWN_META_VALUE = '-';
+
+const SHOWCASE_COST_KEYS = [
+  'priceMudPoints',
+  'costMudPoints',
+  'generationCostMudPoints',
+  'mudPointCost',
+] as const;
+
+const SHOWCASE_AUTHOR_KEYS = [
+  'authorName',
+  'creatorName',
+  'ownerLabel',
+  'ownerName',
+  'authorDisplayName',
+] as const;
+
+export const SHOWCASE_TABS: Array<{ id: ShowcaseTabId; label: string }> = [
+  { id: 'packs', label: '素材包' },
+  { id: 'characters', label: '角色' },
+  { id: 'ui', label: 'UI' },
+  { id: 'music', label: '音乐' },
+  { id: 'effects', label: '特效' },
+  { id: 'scenes', label: '场景' },
+  { id: 'marketing', label: '美宣' },
+  { id: 'games', label: '游戏' },
+];
+
+function assetRecord(asset: EditorAssetSnapshot) {
+  return asset as Record<string, unknown>;
+}
+
+function normalizeText(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function normalizeNumber(value: unknown) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && value.trim()) {
+    const numericValue = Number(value.trim());
+    return Number.isFinite(numericValue) ? numericValue : null;
+  }
+  return null;
+}
+
+function normalizeInt(
+  value: unknown,
+  fallback: number,
+  minValue = 1,
+  maxValue = Number.MAX_SAFE_INTEGER,
+) {
+  const numericValue = normalizeNumber(value);
+  if (numericValue === null) {
+    return fallback;
+  }
+  return Math.min(maxValue, Math.max(minValue, Math.round(numericValue)));
+}
+
+function normalizeAssetKind(asset: EditorAssetSnapshot) {
+  return asset.assetKind?.trim() ?? '';
+}
+
+function getAssetHaystack(asset: EditorAssetSnapshot) {
+  return [
+    asset.label,
+    asset.prompt,
+    asset.actualPrompt,
+    asset.model,
+    asset.provider,
+    asset.sourceType,
+    asset.assetKind,
+    ...(asset.generationInputs?.fields ?? []).flatMap((field) => [
+      field.title,
+      field.value,
+    ]),
+    ...(asset.generationInputs?.references ?? []).flatMap((reference) => [
+      reference.title,
+      reference.label,
+      reference.refType,
+      reference.refId,
+    ]),
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+}
+
+function getAssetReferences(asset: EditorAssetSnapshot) {
+  return asset.generationInputs?.references ?? [];
+}
+
+function getReferenceKey(reference: EditorAssetGenerationInputReference) {
+  return `${reference.refType}:${reference.refId}`;
+}
+
+function getSelfAssetKey(asset: EditorAssetSnapshot) {
+  return `asset:${asset.assetId}`;
+}
+
+function getAssetReferenceKeys(asset: EditorAssetSnapshot) {
+  const keys = [getSelfAssetKey(asset)];
+  if (asset.sourceResourceId?.trim()) {
+    keys.push(`project-resource:${asset.sourceResourceId.trim()}`);
+  }
+  if (asset.assetObjectId?.trim()) {
+    keys.push(`asset-object:${asset.assetObjectId.trim()}`);
+  }
+  if (asset.objectKey?.trim()) {
+    keys.push(`object:${asset.objectKey.trim()}`);
+  }
+  return keys;
+}
+
+function findReference(
+  asset: EditorAssetSnapshot,
+  matcher: (reference: EditorAssetGenerationInputReference) => boolean,
+) {
+  return getAssetReferences(asset).find(matcher) ?? null;
+}
+
+function findSpecReference(asset: EditorAssetSnapshot) {
+  return findReference(asset, (reference) => /规范/u.test(reference.title));
+}
+
+function findCharacterReference(asset: EditorAssetSnapshot) {
+  return findReference(asset, (reference) => /角色图片|角色图/u.test(reference.title));
+}
+
+function findUiDesignReference(asset: EditorAssetSnapshot) {
+  return findReference(asset, (reference) => /UI设计图|UI 图|UI图片/u.test(reference.title));
+}
+
+function isAssetKind(asset: EditorAssetSnapshot, kinds: readonly string[]) {
+  return kinds.includes(normalizeAssetKind(asset));
+}
+
+function isAudioAsset(asset: EditorAssetSnapshot) {
+  const mediaType = normalizeText(assetRecord(asset).mediaType);
+  return (
+    mediaType === 'audio' ||
+    isAssetKind(asset, ['sound-effect', 'background-music']) ||
+    /\.(mp3|wav|m4a|aac|ogg)(?:$|\?)/iu.test(asset.imageSrc)
+  );
+}
+
+function isVideoAsset(asset: EditorAssetSnapshot) {
+  const mediaType = normalizeText(assetRecord(asset).mediaType);
+  return (
+    mediaType === 'video' ||
+    isAssetKind(asset, ['video']) ||
+    /\.(mp4|webm|mov|m4v)(?:$|\?)/iu.test(asset.imageSrc)
+  );
+}
+
+function resolveAssetMediaType(asset: EditorAssetSnapshot): ShowcaseAssetMediaType {
+  if (isAudioAsset(asset)) {
+    return 'audio';
+  }
+  if (isVideoAsset(asset)) {
+    return 'video';
+  }
+  return 'image';
+}
+
+function isSpecAsset(asset: EditorAssetSnapshot) {
+  return isAssetKind(asset, ['spec', 'icon-spec']);
+}
+
+function isCharacterAsset(asset: EditorAssetSnapshot) {
+  return isAssetKind(asset, ['character']);
+}
+
+function isCharacterAnimationAsset(asset: EditorAssetSnapshot) {
+  return isAssetKind(asset, ['character-animation']);
+}
+
+function isUiAsset(asset: EditorAssetSnapshot) {
+  return isAssetKind(asset, ['ui-design', 'icon', 'icon-spritesheet']);
+}
+
+function isMarketingAsset(asset: EditorAssetSnapshot) {
+  const haystack = getAssetHaystack(asset);
+  return (
+    isAssetKind(asset, ['publication-material']) ||
+    /美宣|宣发|宣传|poster|promo|marketing/u.test(haystack)
+  );
+}
+
+function isSceneAsset(asset: EditorAssetSnapshot) {
+  return /场景|scene|background/u.test(getAssetHaystack(asset));
+}
+
+function isEffectAsset(asset: EditorAssetSnapshot) {
+  return /特效|effect|vfx/u.test(getAssetHaystack(asset));
+}
+
+function isGameAsset(asset: EditorAssetSnapshot) {
+  return /游戏工程|game asset|game package|导出工程/u.test(getAssetHaystack(asset));
+}
+
+function addAssetToGroup(
+  groups: Map<string, ShowcaseAssetGroup>,
+  groupId: string,
+  asset: EditorAssetSnapshot,
+  label?: string,
+) {
+  const group = groups.get(groupId);
+  if (group) {
+    if (label && !group.label) {
+      group.label = label;
+    }
+    group.assets.push(asset);
+    return;
+  }
+
+  groups.set(groupId, {
+    id: groupId,
+    label,
+    assets: [asset],
+  });
+}
+
+function mergeAssetAliasGroups(
+  groups: Map<string, ShowcaseAssetGroup>,
+  asset: EditorAssetSnapshot,
+  label?: string,
+) {
+  const aliasGroups = getAssetReferenceKeys(asset)
+    .map((key) => groups.get(key))
+    .filter((group): group is ShowcaseAssetGroup => Boolean(group))
+    .filter(
+      (group, index, list) =>
+        list.findIndex((candidate) => candidate.id === group.id) === index,
+    );
+
+  const targetGroup = aliasGroups[0] ?? null;
+  if (!targetGroup) {
+    return null;
+  }
+
+  if (label && !targetGroup.label) {
+    targetGroup.label = label;
+  }
+
+  aliasGroups.slice(1).forEach((group) => {
+    if (!targetGroup.label && group.label) {
+      targetGroup.label = group.label;
+    }
+    group.assets.forEach((assetInGroup) => {
+      if (
+        !targetGroup.assets.some(
+          (existingAsset) => existingAsset.assetId === assetInGroup.assetId,
+        )
+      ) {
+        targetGroup.assets.push(assetInGroup);
+      }
+    });
+    groups.delete(group.id);
+  });
+
+  return targetGroup;
+}
+
+function sortGroupAssets(assets: EditorAssetSnapshot[]) {
+  return [...assets].sort((left, right) => {
+    const leftRank = isSpecAsset(left) || isCharacterAsset(left) || isAssetKind(left, ['ui-design'])
+      ? 0
+      : 1;
+    const rightRank =
+      isSpecAsset(right) || isCharacterAsset(right) || isAssetKind(right, ['ui-design'])
+        ? 0
+        : 1;
+    if (leftRank !== rightRank) {
+      return leftRank - rightRank;
+    }
+    return (left.createdAt ?? '').localeCompare(right.createdAt ?? '');
+  });
+}
+
+function groupPackAssets(assets: EditorAssetSnapshot[]) {
+  const groups = new Map<string, ShowcaseAssetGroup>();
+  assets.forEach((asset) => {
+    const specReference = findSpecReference(asset);
+    if (specReference) {
+      addAssetToGroup(groups, getReferenceKey(specReference), asset, specReference.label);
+      return;
+    }
+    if (isSpecAsset(asset)) {
+      addAssetToGroup(groups, getSelfAssetKey(asset), asset, asset.label);
+      return;
+    }
+    addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
+  });
+  const specAssets = assets.filter(isSpecAsset);
+  specAssets.forEach((asset) => {
+    const group = mergeAssetAliasGroups(groups, asset, asset.label);
+    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+      group.assets.unshift(asset);
+    }
+  });
+  return [...groups.values()].map((group) => ({
+    ...group,
+    assets: sortGroupAssets(group.assets),
+  }));
+}
+
+function groupCharacterAssets(assets: EditorAssetSnapshot[]) {
+  const groups = new Map<string, ShowcaseAssetGroup>();
+  assets
+    .filter(
+      (asset) =>
+        isCharacterAsset(asset) ||
+        isCharacterAnimationAsset(asset) ||
+        /角色|character/u.test(getAssetHaystack(asset)),
+    )
+    .forEach((asset) => {
+      if (isCharacterAsset(asset)) {
+        addAssetToGroup(groups, getSelfAssetKey(asset), asset, asset.label);
+        return;
+      }
+      const characterReference = findCharacterReference(asset);
+      if (characterReference) {
+        addAssetToGroup(
+          groups,
+          getReferenceKey(characterReference),
+          asset,
+          characterReference.label,
+        );
+        return;
+      }
+      addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
+  });
+  const characterAssets = assets.filter(isCharacterAsset);
+  characterAssets.forEach((asset) => {
+    const group = mergeAssetAliasGroups(groups, asset, asset.label);
+    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+      group.assets.unshift(asset);
+    }
+  });
+  return [...groups.values()].map((group) => ({
+    ...group,
+    assets: sortGroupAssets(group.assets),
+  }));
+}
+
+function groupUiAssets(assets: EditorAssetSnapshot[]) {
+  const groups = new Map<string, ShowcaseAssetGroup>();
+  assets
+    .filter((asset) => isUiAsset(asset) || /\bui\b|界面|图标|icon/u.test(getAssetHaystack(asset)))
+    .forEach((asset) => {
+      if (isAssetKind(asset, ['ui-design'])) {
+        addAssetToGroup(groups, getSelfAssetKey(asset), asset, asset.label);
+        return;
+      }
+      const uiReference = findUiDesignReference(asset) ?? findSpecReference(asset);
+      if (uiReference) {
+        addAssetToGroup(groups, getReferenceKey(uiReference), asset, uiReference.label);
+        return;
+      }
+      addAssetToGroup(groups, `standalone:${asset.assetId}`, asset, asset.label);
+  });
+  const uiDesignAssets = assets.filter((asset) => isAssetKind(asset, ['ui-design']));
+  uiDesignAssets.forEach((asset) => {
+    const group = mergeAssetAliasGroups(groups, asset, asset.label);
+    if (group && !group.assets.some((groupAsset) => groupAsset.assetId === asset.assetId)) {
+      group.assets.unshift(asset);
+    }
+  });
+  return [...groups.values()].map((group) => ({
+    ...group,
+    assets: sortGroupAssets(group.assets),
+  }));
+}
+
+function groupSingleAssets(
+  assets: EditorAssetSnapshot[],
+  predicate: (asset: EditorAssetSnapshot) => boolean,
+) {
+  return assets.filter(predicate).map((asset) => ({
+    id: `asset:${asset.assetId}`,
+    label: asset.label,
+    assets: [asset],
+  }));
+}
+
+function getGroupsForTab(assets: EditorAssetSnapshot[], tab: ShowcaseTabId) {
+  if (tab === 'packs') {
+    return groupPackAssets(assets);
+  }
+  if (tab === 'characters') {
+    return groupCharacterAssets(assets);
+  }
+  if (tab === 'ui') {
+    return groupUiAssets(assets);
+  }
+  if (tab === 'music') {
+    return groupSingleAssets(assets, isAudioAsset);
+  }
+  if (tab === 'marketing') {
+    return groupSingleAssets(assets, isMarketingAsset);
+  }
+  if (tab === 'effects') {
+    return groupSingleAssets(assets, isEffectAsset);
+  }
+  if (tab === 'scenes') {
+    return groupSingleAssets(assets, isSceneAsset);
+  }
+  return groupSingleAssets(assets, isGameAsset);
+}
+
+function resolveAssetPrompt(asset: EditorAssetSnapshot) {
+  const directPrompt = asset.prompt?.trim() || asset.actualPrompt?.trim();
+  if (directPrompt) {
+    return directPrompt;
+  }
+
+  const generationFields = asset.generationInputs?.fields ?? [];
+  const firstPromptField =
+    generationFields.find((field) => /提示词|描述|设定|prompt/u.test(field.title)) ??
+    generationFields[0];
+  return firstPromptField?.value?.trim() || UNKNOWN_META_VALUE;
+}
+
+function resolveGroupPrompt(assets: EditorAssetSnapshot[]) {
+  return assets.map(resolveAssetPrompt).find((value) => value !== UNKNOWN_META_VALUE) ?? UNKNOWN_META_VALUE;
+}
+
+function resolveAssetAuthor(
+  asset: EditorAssetSnapshot,
+  fallbackAuthorName?: string | null,
+) {
+  const record = assetRecord(asset);
+  for (const key of SHOWCASE_AUTHOR_KEYS) {
+    const value = normalizeText(record[key]);
+    if (value) {
+      return value;
+    }
+  }
+  return fallbackAuthorName?.trim() || UNKNOWN_META_VALUE;
+}
+
+function resolveGroupAuthor(
+  assets: EditorAssetSnapshot[],
+  fallbackAuthorName?: string | null,
+) {
+  return (
+    assets
+      .map((asset) => resolveAssetAuthor(asset, fallbackAuthorName))
+      .find((value) => value !== UNKNOWN_META_VALUE) ?? UNKNOWN_META_VALUE
+  );
+}
+
+function resolveAssetCost(asset: EditorAssetSnapshot) {
+  const record = assetRecord(asset);
+  for (const key of SHOWCASE_COST_KEYS) {
+    const value = normalizeNumber(record[key]);
+    if (value !== null && value >= 0) {
+      return value;
+    }
+  }
+  const inferredValue = inferAssetCost(asset);
+  if (inferredValue !== null && inferredValue >= 0) {
+    return inferredValue;
+  }
+  return null;
+}
+
+function getAssetCostKey(asset: EditorAssetSnapshot) {
+  if (asset.taskId?.trim()) {
+    return `task:${asset.taskId.trim()}`;
+  }
+  if (asset.objectKey?.trim()) {
+    return `object:${asset.objectKey.trim()}`;
+  }
+  return `asset:${asset.assetId}`;
+}
+
+function inferAssetCost(asset: EditorAssetSnapshot) {
+  const kind = normalizeAssetKind(asset);
+  const model = asset.model;
+  if (kind === 'sound-effect') {
+    return calculateEditorSoundEffectPrice(model ?? DEFAULT_SOUND_EFFECT_MODEL);
+  }
+  if (kind === 'background-music') {
+    return calculateEditorBackgroundMusicPrice(
+      model ?? DEFAULT_BACKGROUND_MUSIC_MODEL,
+    );
+  }
+  if (kind === 'character-animation') {
+    return calculateCharacterAnimationPrice(
+      model ?? CHARACTER_ANIMATION_MODEL,
+      inferVideoResolution(asset, ['480p', '720p'], '480p') as '480p' | '720p',
+      normalizeInt(asset.durationSeconds, 4, 4, 6),
+    );
+  }
+  if (kind === 'video' || isVideoAsset(asset)) {
+    return calculateEditorVideoPrice(
+      model ?? DEFAULT_VIDEO_MODEL,
+      inferVideoResolution(asset, ['480p', '720p', '1080p'], '480p') as
+        | '480p'
+        | '720p'
+        | '1080p',
+      normalizeInt(asset.durationSeconds, DEFAULT_VIDEO_DURATION_SECONDS, 4, 15),
+    );
+  }
+  if (asset.sourceType === 'generated' || kind) {
+    return calculateEditorImageGenerationPrice({ kind, model });
+  }
+  return null;
+}
+
+function inferVideoResolution(
+  asset: EditorAssetSnapshot,
+  allowedValues: string[],
+  fallback: string,
+) {
+  const fields = asset.generationInputs?.fields ?? [];
+  const fieldValue = fields
+    .flatMap((field) => [field.title, field.value])
+    .map((value) => value.trim())
+    .find((value) => /\b(?:480p|720p|1080p)\b/iu.test(value));
+  const matchedValue = fieldValue?.match(/\b(480p|720p|1080p)\b/iu)?.[1];
+  if (matchedValue && allowedValues.includes(matchedValue)) {
+    return matchedValue;
+  }
+  return fallback;
+}
+
+function resolveGroupCost(assets: EditorAssetSnapshot[]) {
+  const resolvedCosts = new Map<string, number>();
+  assets.forEach((asset) => {
+    const cost = resolveAssetCost(asset);
+    if (cost !== null) {
+      resolvedCosts.set(getAssetCostKey(asset), cost);
+    }
+  });
+  const costs = [...resolvedCosts.values()];
+  if (!costs.length) {
+    return UNKNOWN_META_VALUE;
+  }
+  const totalCost = costs.reduce((sum, value) => sum + value, 0);
+  return `${totalCost}泥点`;
+}
+
+function toAssetPreview(asset: EditorAssetSnapshot): ShowcaseAssetPreview {
+  return {
+    id: asset.assetId,
+    label: asset.label,
+    src: asset.imageSrc,
+    objectKey: asset.objectKey,
+    mediaType: resolveAssetMediaType(asset),
+    width: asset.width,
+    height: asset.height,
+  };
+}
+
+function toLibraryShowcaseItem(
+  group: ShowcaseAssetGroup,
+  fallbackAuthorName?: string | null,
+): ShowcaseAssetItem | null {
+  const sortedAssets = sortGroupAssets(group.assets);
+  const previews = sortedAssets.map(toAssetPreview).filter((preview) => preview.src.trim());
+  if (!previews.length) {
+    return null;
+  }
+  const primaryAsset = sortedAssets[0];
+  const label =
+    group.label?.trim() ||
+    primaryAsset?.label?.trim() ||
+    `${previews[0]?.label ?? '素材'}组合`;
+  return {
+    id: group.id,
+    label,
+    previews,
+    prompt: resolveGroupPrompt(sortedAssets),
+    author: resolveGroupAuthor(sortedAssets, fallbackAuthorName),
+    cost: resolveGroupCost(sortedAssets),
+  };
+}
+
+function matchesPublicGalleryTab(
+  entry: PlatformPublicGalleryCard,
+  tab: ShowcaseTabId,
+) {
+  if (tab === 'packs') {
+    return true;
+  }
+  if (tab === 'games') {
+    return false;
+  }
+
+  const themeTags = 'themeTags' in entry ? entry.themeTags : [];
+  const haystack = [
+    entry.worldName,
+    entry.subtitle,
+    entry.summaryText,
+    entry.sourceType,
+    ...themeTags,
+  ]
+    .join(' ')
+    .toLowerCase();
+
+  if (tab === 'characters') {
+    return /角色|character|rpg|visual/u.test(haystack);
+  }
+  if (tab === 'ui') {
+    return /\bui\b|界面|图标|icon|puzzle/u.test(haystack);
+  }
+  if (tab === 'music') {
+    return /音乐|音效|audio|music|sound/u.test(haystack);
+  }
+  if (tab === 'marketing') {
+    return /美宣|宣传|poster|video|视觉|visual/u.test(haystack);
+  }
+  if (tab === 'effects') {
+    return /特效|effect|vfx/u.test(haystack);
+  }
+  if (tab === 'scenes') {
+    return /场景|scene|background|world|rpg/u.test(haystack);
+  }
+  return false;
+}
+
+function toPublicGalleryShowcaseItems(
+  entries: PlatformPublicGalleryCard[],
+  tab: ShowcaseTabId,
+): ShowcaseAssetItem[] {
+  const usedImageSrcs = new Set<string>();
+  const items: ShowcaseAssetItem[] = [];
+
+  entries
+    .filter((entry) => matchesPublicGalleryTab(entry, tab))
+    .forEach((entry) => {
+      const coverImageSrc = resolvePlatformWorldCoverImage(entry).trim();
+      const imageCandidates = [
+        ...resolvePlatformWorldCoverSlides(entry).map((slide) => ({
+          src: slide.imageSrc.trim(),
+          label: slide.label?.trim() || entry.worldName,
+        })),
+        { src: coverImageSrc, label: entry.worldName },
+      ].filter((candidate) => candidate.src);
+
+      imageCandidates.forEach((candidate, index) => {
+        if (usedImageSrcs.has(candidate.src)) {
+          return;
+        }
+        usedImageSrcs.add(candidate.src);
+        items.push({
+          id: `public:${entry.sourceType}:${entry.profileId}:${index}`,
+          label: index === 0 ? entry.worldName : `${entry.worldName} ${index + 1}`,
+          previews: [
+            {
+              id: `public:${entry.profileId}:${index}`,
+              label: candidate.label,
+              src: candidate.src,
+              mediaType: 'image',
+              width: index === 0 ? 720 : 640,
+              height: index === 0 ? 480 : 720,
+            },
+          ],
+          prompt: entry.summaryText || entry.subtitle || UNKNOWN_META_VALUE,
+          author: resolvePlatformWorkAuthorDisplayName(entry),
+          cost: UNKNOWN_META_VALUE,
+        });
+      });
+    });
+
+  return items.slice(0, 36);
+}
+
+export function buildCreationShowcaseItems({
+  activeTab,
+  assetLibrary,
+  publicGalleryEntries,
+  fallbackAuthorName,
+}: {
+  activeTab: ShowcaseTabId;
+  assetLibrary: EditorAssetLibrarySnapshot | null;
+  publicGalleryEntries: PlatformPublicGalleryCard[];
+  fallbackAuthorName?: string | null;
+}) {
+  const libraryItems = getGroupsForTab(assetLibrary?.assets ?? [], activeTab)
+    .map((group) => toLibraryShowcaseItem(group, fallbackAuthorName))
+    .filter((item): item is ShowcaseAssetItem => item !== null);
+
+  if (libraryItems.length > 0) {
+    return libraryItems.slice(0, 36);
+  }
+
+  return toPublicGalleryShowcaseItems(publicGalleryEntries, activeTab);
+}
diff --git a/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx b/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx
new file mode 100644
index 000000000..2404aa518
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetFolderSectionView.tsx
@@ -0,0 +1,257 @@
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  Folder,
+  ImagePlus,
+  PencilLine,
+  Trash2,
+  X,
+} from 'lucide-react';
+import type { Dispatch, SetStateAction } from 'react';
+
+import { PlatformTextField } from '../common/PlatformTextField';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import {
+  ASSET_DRAG_MIME_TYPE,
+  getDraggedAssetId,
+  hasDataTransferType,
+} from './ImageCanvasEditorModel';
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+  EditorAssetFolder,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasAssetRowView } from './ImageCanvasAssetRowView';
+import type {
+  GroupedEditorAssetFolder,
+  UploadFilesOptions,
+} from './ImageCanvasAssetLibraryPanelView';
+
+type ImageCanvasAssetFolderSectionViewProps = {
+  folder: GroupedEditorAssetFolder;
+  assetPointerDragRef: { current: AssetPointerDragState | null };
+  suppressAssetClickRef: { current: boolean };
+  isAssetSelectionMode: boolean;
+  selectedAssetIds: Set<string>;
+  assetMoveDropFolderId: string | null;
+  renamingFolder: { folderId: string; value: string } | null;
+  renamingAsset: { assetId: string; value: string } | null;
+  setRenamingFolder: Dispatch<
+    SetStateAction<{ folderId: string; value: string } | null>
+  >;
+  setRenamingAsset: Dispatch<
+    SetStateAction<{ assetId: string; value: string } | null>
+  >;
+  setActiveUploadFolderId: Dispatch<SetStateAction<string>>;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setSelectedAssetIds: Dispatch<SetStateAction<Set<string>>>;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  addUploadedFiles: (files: FileList | File[], options?: UploadFilesOptions) => void;
+  requestUpload: (target: UploadTarget) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  toggleAssetFolder: (folderId: string) => void;
+  startRenamingFolder: (folder: EditorAssetFolder) => void;
+  commitFolderRename: (folder: EditorAssetFolder) => void;
+  deleteAssetFolder: (folder: EditorAssetFolder) => void;
+  startRenamingAsset: (asset: EditorAsset) => void;
+  commitAssetRename: (asset: EditorAsset) => void;
+  deleteUploadedAsset: (asset: EditorAsset) => void;
+  toggleAssetSelected: (assetId: string) => void;
+  addAssetLayer: (asset: EditorAsset) => void;
+};
+
+export function ImageCanvasAssetFolderSectionView({
+  folder,
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  isAssetSelectionMode,
+  selectedAssetIds,
+  assetMoveDropFolderId,
+  renamingFolder,
+  renamingAsset,
+  setRenamingFolder,
+  setRenamingAsset,
+  setActiveUploadFolderId,
+  setUploadDropTarget,
+  setAssetPointerDrag,
+  setSelectedAssetIds,
+  updateAssetMoveDropFolder,
+  addUploadedFiles,
+  requestUpload,
+  moveAssetToFolder,
+  toggleAssetFolder,
+  startRenamingFolder,
+  commitFolderRename,
+  deleteAssetFolder,
+  startRenamingAsset,
+  commitAssetRename,
+  deleteUploadedAsset,
+  toggleAssetSelected,
+  addAssetLayer,
+}: ImageCanvasAssetFolderSectionViewProps) {
+  return (
+    <section
+      className={[
+        'image-canvas-editor__asset-folder',
+        assetMoveDropFolderId === folder.id
+          ? 'image-canvas-editor__asset-folder--move-target'
+          : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      aria-label={folder.label}
+      data-asset-folder-id={folder.id}
+      onDragOver={(event) => {
+        if (hasDataTransferType(event.dataTransfer, ASSET_DRAG_MIME_TYPE)) {
+          event.preventDefault();
+          event.stopPropagation();
+          setUploadDropTarget(null);
+          updateAssetMoveDropFolder(folder.id);
+          event.dataTransfer.dropEffect = 'move';
+          return;
+        }
+        if (hasDataTransferType(event.dataTransfer, 'Files')) {
+          event.preventDefault();
+          event.stopPropagation();
+          setUploadDropTarget('assets');
+          event.dataTransfer.dropEffect = 'copy';
+        }
+      }}
+      onDrop={(event) => {
+        const movingAssetId = getDraggedAssetId(event.dataTransfer);
+        if (movingAssetId) {
+          event.preventDefault();
+          event.stopPropagation();
+          setUploadDropTarget(null);
+          updateAssetMoveDropFolder(null);
+          moveAssetToFolder(movingAssetId, folder.id);
+          return;
+        }
+        if (!event.dataTransfer.files.length) {
+          return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        setUploadDropTarget(null);
+        updateAssetMoveDropFolder(null);
+        addUploadedFiles(event.dataTransfer.files, {
+          folderId: folder.id,
+        });
+      }}
+    >
+      <div
+        className="image-canvas-editor__asset-folder-header"
+        data-asset-folder-header-id={folder.id}
+      >
+        <EditorIconButton
+          label={`${folder.collapsed ? '展开' : '折叠'}${folder.label}`}
+          title={folder.collapsed ? '展开' : '折叠'}
+          icon={folder.collapsed ? ChevronRight : ChevronDown}
+          expanded={!folder.collapsed}
+          onClick={() => toggleAssetFolder(folder.id)}
+        />
+        <Folder className="h-4 w-4" />
+        {renamingFolder?.folderId === folder.id ? (
+          <PlatformTextField
+            aria-label={`重命名文件夹${folder.label}`}
+            value={renamingFolder.value}
+            autoFocus
+            size="xs"
+            density="compact"
+            className="image-canvas-editor__folder-rename-input"
+            onChange={(event) =>
+              setRenamingFolder({
+                folderId: folder.id,
+                value: event.target.value,
+              })
+            }
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                event.preventDefault();
+                commitFolderRename(folder);
+              }
+              if (event.key === 'Escape') {
+                event.preventDefault();
+                setRenamingFolder(null);
+              }
+            }}
+          />
+        ) : (
+          <span>{folder.label}</span>
+        )}
+        <span>{folder.assets.length}</span>
+        {renamingFolder?.folderId === folder.id ? (
+          <>
+            <EditorIconButton
+              label={`保存文件夹${folder.label}名称`}
+              title="保存"
+              icon={Check}
+              onClick={() => commitFolderRename(folder)}
+            />
+            <EditorIconButton
+              label={`取消重命名文件夹${folder.label}`}
+              title="取消"
+              icon={X}
+              onClick={() => setRenamingFolder(null)}
+            />
+          </>
+        ) : (
+          <EditorIconButton
+            label={`重命名文件夹${folder.label}`}
+            title="重命名"
+            icon={PencilLine}
+            onClick={() => startRenamingFolder(folder)}
+          />
+        )}
+        {!folder.systemDefault ? (
+          <EditorIconButton
+            label={`删除文件夹${folder.label}`}
+            title="删除"
+            icon={Trash2}
+            onClick={() => deleteAssetFolder(folder)}
+          />
+        ) : null}
+        <EditorIconButton
+          label={`上传到${folder.label}`}
+          title="上传"
+          icon={ImagePlus}
+          onClick={() => {
+            setActiveUploadFolderId(folder.id);
+            requestUpload('asset');
+          }}
+        />
+      </div>
+      <div
+        className="image-canvas-editor__asset-folder-list"
+        hidden={folder.collapsed}
+      >
+        {folder.assets.map((asset) => (
+          <ImageCanvasAssetRowView
+            key={asset.id}
+            asset={asset}
+            assetPointerDragRef={assetPointerDragRef}
+            suppressAssetClickRef={suppressAssetClickRef}
+            isAssetSelectionMode={isAssetSelectionMode}
+            selectedAssetIds={selectedAssetIds}
+            renamingAsset={renamingAsset}
+            setRenamingAsset={setRenamingAsset}
+            setUploadDropTarget={setUploadDropTarget}
+            setAssetPointerDrag={setAssetPointerDrag}
+            setSelectedAssetIds={setSelectedAssetIds}
+            updateAssetMoveDropFolder={updateAssetMoveDropFolder}
+            addUploadedFiles={addUploadedFiles}
+            moveAssetToFolder={moveAssetToFolder}
+            startRenamingAsset={startRenamingAsset}
+            commitAssetRename={commitAssetRename}
+            deleteUploadedAsset={deleteUploadedAsset}
+            toggleAssetSelected={toggleAssetSelected}
+            addAssetLayer={addAssetLayer}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
new file mode 100644
index 000000000..eb130ca2a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetLibraryModel.test.ts
@@ -0,0 +1,328 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import {
+  areAllSelectableAssetsSelected,
+  createAssetMarqueeFromPointer,
+  createAssetMarqueeSelectionRect,
+  createLocalAssetFolder,
+  deleteAssetFolderLocally,
+  getSelectableAssets,
+  groupAssetsByFolder,
+  moveAssetToFolderLocally,
+  moveAssetMarqueeToPointer,
+  removeAssetById,
+  removeSelectedAssets,
+  renameAssetById,
+  renameAssetFolderById,
+  replaceLocalAssetFolder,
+  resolveAllAssetSelection,
+  resolveAssetFolderIdFromPoint,
+  resolveDefaultAssetFolder,
+  resolvePinnedAssetMoveFolderId,
+  selectUploadedAssetsInRect,
+  toggleAssetFolderCollapsed,
+  toggleAssetSelection,
+} from './ImageCanvasAssetLibraryModel';
+
+function createFolder(
+  overrides: Partial<EditorAssetFolder> = {},
+): EditorAssetFolder {
+  return {
+    id: 'project',
+    label: '项目素材',
+    collapsed: false,
+    systemDefault: true,
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function createAsset(overrides: Partial<EditorAsset> = {}): EditorAsset {
+  return {
+    id: 'asset-a',
+    label: '素材A',
+    src: 'data:image/png;base64,YQ==',
+    width: 320,
+    height: 240,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasAssetLibraryModel', () => {
+  it('groups assets by folder and resolves selectable uploaded assets', () => {
+    const folders = [
+      createFolder(),
+      createFolder({ id: 'folder-role', label: '角色素材' }),
+    ];
+    const assets = [
+      createAsset({ id: 'asset-a', folderId: 'project' }),
+      createAsset({
+        id: 'asset-b',
+        label: '素材B',
+        folderId: 'folder-role',
+      }),
+      createAsset({
+        id: 'built-in',
+        label: '内置素材',
+        sourceKind: 'built-in',
+      }),
+    ];
+
+    expect(groupAssetsByFolder(folders, assets)).toMatchObject([
+      { id: 'project', assets: [{ id: 'asset-a' }, { id: 'built-in' }] },
+      { id: 'folder-role', assets: [{ id: 'asset-b' }] },
+    ]);
+    expect(getSelectableAssets(assets).map((asset) => asset.id)).toEqual([
+      'asset-a',
+      'asset-b',
+    ]);
+  });
+
+  it('renames assets, toggles folders and creates local folders', () => {
+    expect(renameAssetById([createAsset()], 'asset-a', '新名字')[0]).toMatchObject(
+      { label: '新名字' },
+    );
+    expect(
+      renameAssetFolderById([createFolder()], 'project', '默认素材')[0],
+    ).toMatchObject({ label: '默认素材' });
+    expect(toggleAssetFolderCollapsed([createFolder()], 'project')[0]).toMatchObject(
+      { collapsed: true },
+    );
+    expect(
+      createLocalAssetFolder({
+        folderId: 'folder-local',
+        label: '角色素材',
+      }),
+    ).toEqual({
+      id: 'folder-local',
+      label: '角色素材',
+      collapsed: false,
+      systemDefault: false,
+      persisted: false,
+    });
+  });
+
+  it('replaces local folder ids in folders and contained assets', () => {
+    const result = replaceLocalAssetFolder({
+      folders: [createFolder(), createFolder({ id: 'folder-local' })],
+      assets: [createAsset({ folderId: 'folder-local' })],
+      localFolderId: 'folder-local',
+      persistedFolder: {
+        folderId: 'folder-role',
+        label: '角色素材',
+        collapsed: false,
+        systemDefault: false,
+      },
+    });
+
+    expect(result.folders[1]).toEqual({
+      id: 'folder-role',
+      label: '角色素材',
+      collapsed: false,
+      systemDefault: false,
+      persisted: true,
+    });
+    expect(result.assets[0]).toMatchObject({ folderId: 'folder-role' });
+  });
+
+  it('deletes assets and moves deleted folder contents to the default folder', () => {
+    const folders = [
+      createFolder(),
+      createFolder({ id: 'folder-role', systemDefault: false }),
+    ];
+    const assets = [
+      createAsset({ id: 'asset-a', folderId: 'folder-role' }),
+      createAsset({ id: 'asset-b', folderId: 'project' }),
+    ];
+
+    expect(removeAssetById(assets, 'asset-a').map((asset) => asset.id)).toEqual([
+      'asset-b',
+    ]);
+    expect(resolveDefaultAssetFolder(folders)?.id).toBe('project');
+    expect(
+      deleteAssetFolderLocally({
+        folders,
+        assets,
+        folderId: 'folder-role',
+        defaultFolderId: 'project',
+      }),
+    ).toMatchObject({
+      folders: [{ id: 'project' }],
+      assets: [
+        { id: 'asset-a', folderId: 'project' },
+        { id: 'asset-b', folderId: 'project' },
+      ],
+    });
+  });
+
+  it('toggles selection, selects all uploaded assets and removes selected assets', () => {
+    const assets = [
+      createAsset({ id: 'asset-a' }),
+      createAsset({ id: 'asset-b' }),
+    ];
+    const selected = toggleAssetSelection(new Set<string>(), 'asset-a');
+
+    expect([...selected]).toEqual(['asset-a']);
+    expect([...toggleAssetSelection(selected, 'asset-a')]).toEqual([]);
+    expect(areAllSelectableAssetsSelected(assets, new Set(['asset-a']))).toBe(
+      false,
+    );
+    const allSelected = resolveAllAssetSelection({
+      allSelectableAssetsSelected: false,
+      selectableAssets: assets,
+    });
+    expect([...allSelected]).toEqual(['asset-a', 'asset-b']);
+    const removal = removeSelectedAssets(assets, new Set(['asset-b']));
+    expect(removal.assets.map((asset) => asset.id)).toEqual(['asset-a']);
+    expect(removal.deletedAssets.map((asset) => asset.id)).toEqual(['asset-b']);
+  });
+
+  it('moves assets between folders locally', () => {
+    expect(
+      moveAssetToFolderLocally([createAsset()], 'asset-a', 'folder-role')[0],
+    ).toMatchObject({ folderId: 'folder-role' });
+  });
+
+  it('resolves folder hit targets from pointer coordinates', () => {
+    const folders = [
+      {
+        folderId: 'project',
+        rect: { left: 10, right: 110, top: 10, bottom: 80 },
+      },
+      {
+        folderId: 'folder-role',
+        rect: { left: 10, right: 110, top: 81, bottom: 150 },
+      },
+    ];
+
+    expect(
+      resolveAssetFolderIdFromPoint({
+        point: { clientX: 40, clientY: 80 },
+        listRect: { left: 0, right: 140, top: 0, bottom: 180 },
+        folders,
+      }),
+    ).toBe('project');
+    expect(
+      resolveAssetFolderIdFromPoint({
+        point: { clientX: 5, clientY: 40 },
+        listRect: { left: 10, right: 140, top: 0, bottom: 180 },
+        folders,
+      }),
+    ).toBeNull();
+    expect(
+      resolveAssetFolderIdFromPoint({
+        point: { clientX: 120, clientY: 40 },
+        listRect: { left: 0, right: 140, top: 0, bottom: 180 },
+        folders,
+      }),
+    ).toBeNull();
+  });
+
+  it('pins asset move folder labels only when their header is outside the list viewport', () => {
+    const listRect = { left: 0, right: 120, top: 100, bottom: 240 };
+
+    expect(
+      resolvePinnedAssetMoveFolderId({
+        folderId: 'folder-role',
+        listRect,
+        headerRect: { left: 0, right: 120, top: 40, bottom: 80 },
+      }),
+    ).toBe('folder-role');
+    expect(
+      resolvePinnedAssetMoveFolderId({
+        folderId: 'folder-role',
+        listRect,
+        headerRect: { left: 0, right: 120, top: 260, bottom: 300 },
+      }),
+    ).toBe('folder-role');
+    expect(
+      resolvePinnedAssetMoveFolderId({
+        folderId: 'folder-role',
+        listRect,
+        headerRect: { left: 0, right: 120, top: 120, bottom: 150 },
+      }),
+    ).toBeNull();
+    expect(
+      resolvePinnedAssetMoveFolderId({
+        folderId: null,
+        listRect,
+        headerRect: { left: 0, right: 120, top: 40, bottom: 80 },
+      }),
+    ).toBeNull();
+  });
+
+  it('updates marquee geometry from pointer coordinates and normalizes reverse drags', () => {
+    const marquee = createAssetMarqueeFromPointer({
+      pointerId: 5,
+      point: { clientX: 180, clientY: 220 },
+      containerRect: { left: 100, top: 200 },
+    });
+
+    expect(marquee).toEqual({
+      pointerId: 5,
+      startX: 80,
+      startY: 20,
+      currentX: 80,
+      currentY: 20,
+    });
+    expect(
+      moveAssetMarqueeToPointer({
+        marquee,
+        point: { clientX: 120, clientY: 205 },
+        containerRect: { left: 100, top: 200 },
+      }),
+    ).toMatchObject({ currentX: 20, currentY: 5 });
+    expect(
+      createAssetMarqueeSelectionRect({
+        marquee,
+        point: { clientX: 120, clientY: 205 },
+        containerRect: { left: 100, top: 200 },
+      }),
+    ).toEqual({
+      left: 120,
+      right: 180,
+      top: 205,
+      bottom: 220,
+    });
+  });
+
+  it('selects only uploaded assets intersecting the marquee rectangle', () => {
+    const assets = [
+      createAsset({ id: 'asset-a' }),
+      createAsset({ id: 'asset-b' }),
+      createAsset({ id: 'built-in', sourceKind: 'built-in' }),
+    ];
+    const selectedIds = selectUploadedAssetsInRect({
+      assets,
+      assetTargets: [
+        {
+          assetId: 'asset-a',
+          rect: { left: 10, right: 20, top: 10, bottom: 20 },
+        },
+        {
+          assetId: 'asset-b',
+          rect: { left: 30, right: 40, top: 30, bottom: 40 },
+        },
+        {
+          assetId: 'built-in',
+          rect: { left: 15, right: 25, top: 15, bottom: 25 },
+        },
+        {
+          assetId: 'missing',
+          rect: { left: 15, right: 25, top: 15, bottom: 25 },
+        },
+      ],
+      selectionRect: { left: 20, right: 35, top: 20, bottom: 35 },
+    });
+
+    expect([...selectedIds]).toEqual(['asset-a', 'asset-b']);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryModel.ts b/src/components/image-editor/ImageCanvasAssetLibraryModel.ts
new file mode 100644
index 000000000..04a859de3
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetLibraryModel.ts
@@ -0,0 +1,382 @@
+import type {
+  AssetMarqueeState,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+
+type ClientRectLike = Pick<DOMRect, 'bottom' | 'left' | 'right' | 'top'>;
+
+type ClientPoint = {
+  clientX: number;
+  clientY: number;
+};
+
+type AssetFolderHitTarget = {
+  folderId: string;
+  rect: ClientRectLike;
+};
+
+type AssetHitTarget = {
+  assetId: string;
+  rect: ClientRectLike;
+};
+
+export type GroupedAssetFolder = EditorAssetFolder & {
+  assets: EditorAsset[];
+};
+
+function isPointInRect(point: ClientPoint, rect: ClientRectLike) {
+  return (
+    point.clientX >= rect.left &&
+    point.clientX <= rect.right &&
+    point.clientY >= rect.top &&
+    point.clientY <= rect.bottom
+  );
+}
+
+function doRectsIntersect(rect: ClientRectLike, selectionRect: ClientRectLike) {
+  return (
+    rect.left <= selectionRect.right &&
+    rect.right >= selectionRect.left &&
+    rect.top <= selectionRect.bottom &&
+    rect.bottom >= selectionRect.top
+  );
+}
+
+export function resolveAssetFolderIdFromPoint({
+  point,
+  listRect,
+  folders,
+}: {
+  point: ClientPoint;
+  listRect: ClientRectLike | null | undefined;
+  folders: AssetFolderHitTarget[];
+}) {
+  if (!listRect || !isPointInRect(point, listRect)) {
+    return null;
+  }
+  const matchedFolder = folders.find((folder) =>
+    isPointInRect(point, folder.rect),
+  );
+  return matchedFolder?.folderId ?? null;
+}
+
+export function resolvePinnedAssetMoveFolderId({
+  folderId,
+  listRect,
+  headerRect,
+}: {
+  folderId: string | null;
+  listRect: ClientRectLike | null | undefined;
+  headerRect: ClientRectLike | null | undefined;
+}) {
+  if (
+    !folderId ||
+    !listRect ||
+    !headerRect ||
+    (headerRect.bottom >= listRect.top && headerRect.top <= listRect.bottom)
+  ) {
+    return null;
+  }
+  return folderId;
+}
+
+export function shouldStartAssetMarquee({
+  isAssetSelectionMode,
+  button,
+  isBlockedTarget,
+}: {
+  isAssetSelectionMode: boolean;
+  button: number;
+  isBlockedTarget: boolean;
+}) {
+  return isAssetSelectionMode && button === 0 && !isBlockedTarget;
+}
+
+export function createAssetMarqueeFromPointer({
+  pointerId,
+  point,
+  containerRect,
+}: {
+  pointerId: number;
+  point: ClientPoint;
+  containerRect: Pick<DOMRect, 'left' | 'top'> | null | undefined;
+}): AssetMarqueeState {
+  const startX = point.clientX - (containerRect?.left ?? 0);
+  const startY = point.clientY - (containerRect?.top ?? 0);
+  return {
+    pointerId,
+    startX,
+    startY,
+    currentX: startX,
+    currentY: startY,
+  };
+}
+
+export function moveAssetMarqueeToPointer({
+  marquee,
+  point,
+  containerRect,
+}: {
+  marquee: AssetMarqueeState;
+  point: ClientPoint;
+  containerRect: Pick<DOMRect, 'left' | 'top'> | null | undefined;
+}) {
+  return {
+    ...marquee,
+    currentX: point.clientX - (containerRect?.left ?? 0),
+    currentY: point.clientY - (containerRect?.top ?? 0),
+  };
+}
+
+export function createAssetMarqueeSelectionRect({
+  marquee,
+  point,
+  containerRect,
+}: {
+  marquee: AssetMarqueeState;
+  point: ClientPoint;
+  containerRect: Pick<DOMRect, 'left' | 'top'> | null | undefined;
+}): ClientRectLike {
+  const startClientX = (containerRect?.left ?? 0) + marquee.startX;
+  const startClientY = (containerRect?.top ?? 0) + marquee.startY;
+  return {
+    left: Math.min(startClientX, point.clientX),
+    right: Math.max(startClientX, point.clientX),
+    top: Math.min(startClientY, point.clientY),
+    bottom: Math.max(startClientY, point.clientY),
+  };
+}
+
+export function selectUploadedAssetsInRect({
+  assets,
+  assetTargets,
+  selectionRect,
+}: {
+  assets: EditorAsset[];
+  assetTargets: AssetHitTarget[];
+  selectionRect: ClientRectLike;
+}) {
+  const uploadedAssetIds = new Set(
+    assets
+      .filter((asset) => asset.sourceKind === 'uploaded')
+      .map((asset) => asset.id),
+  );
+  return new Set(
+    assetTargets
+      .filter(
+        (target) =>
+          uploadedAssetIds.has(target.assetId) &&
+          doRectsIntersect(target.rect, selectionRect),
+      )
+      .map((target) => target.assetId),
+  );
+}
+
+export function groupAssetsByFolder(
+  assetFolders: EditorAssetFolder[],
+  assets: EditorAsset[],
+): GroupedAssetFolder[] {
+  return assetFolders.map((folder) => ({
+    ...folder,
+    assets: assets.filter((asset) => asset.folderId === folder.id),
+  }));
+}
+
+export function getSelectableAssets(assets: EditorAsset[]) {
+  return assets.filter((asset) => asset.sourceKind === 'uploaded');
+}
+
+export function areAllSelectableAssetsSelected(
+  selectableAssets: EditorAsset[],
+  selectedAssetIds: Set<string>,
+) {
+  return (
+    selectableAssets.length > 0 &&
+    selectableAssets.every((asset) => selectedAssetIds.has(asset.id))
+  );
+}
+
+export function renameAssetById(
+  assets: EditorAsset[],
+  assetId: string,
+  label: string,
+) {
+  return assets.map((asset) =>
+    asset.id === assetId
+      ? {
+          ...asset,
+          label,
+        }
+      : asset,
+  );
+}
+
+export function toggleAssetFolderCollapsed(
+  assetFolders: EditorAssetFolder[],
+  folderId: string,
+) {
+  return assetFolders.map((folder) =>
+    folder.id === folderId
+      ? {
+          ...folder,
+          collapsed: !folder.collapsed,
+        }
+      : folder,
+  );
+}
+
+export function createLocalAssetFolder({
+  folderId,
+  label,
+}: {
+  folderId: string;
+  label: string;
+}): EditorAssetFolder {
+  return {
+    id: folderId,
+    label,
+    collapsed: false,
+    systemDefault: false,
+    persisted: false,
+  };
+}
+
+export function replaceLocalAssetFolder({
+  folders,
+  assets,
+  localFolderId,
+  persistedFolder,
+}: {
+  folders: EditorAssetFolder[];
+  assets: EditorAsset[];
+  localFolderId: string;
+  persistedFolder: {
+    folderId: string;
+    label: string;
+    collapsed: boolean;
+    systemDefault: boolean;
+  };
+}) {
+  return {
+    folders: folders.map((folder) =>
+      folder.id === localFolderId
+        ? {
+            id: persistedFolder.folderId,
+            label: persistedFolder.label,
+            collapsed: persistedFolder.collapsed,
+            systemDefault: persistedFolder.systemDefault,
+            persisted: true,
+          }
+        : folder,
+    ),
+    assets: assets.map((asset) =>
+      asset.folderId === localFolderId
+        ? {
+            ...asset,
+            folderId: persistedFolder.folderId,
+          }
+        : asset,
+    ),
+  };
+}
+
+export function removeAssetById(assets: EditorAsset[], assetId: string) {
+  return assets.filter((asset) => asset.id !== assetId);
+}
+
+export function renameAssetFolderById(
+  assetFolders: EditorAssetFolder[],
+  folderId: string,
+  label: string,
+) {
+  return assetFolders.map((folder) =>
+    folder.id === folderId
+      ? {
+          ...folder,
+          label,
+        }
+      : folder,
+  );
+}
+
+export function resolveDefaultAssetFolder(assetFolders: EditorAssetFolder[]) {
+  return (
+    assetFolders.find((folder) => folder.systemDefault) ?? assetFolders[0] ?? null
+  );
+}
+
+export function deleteAssetFolderLocally({
+  folders,
+  assets,
+  folderId,
+  defaultFolderId,
+}: {
+  folders: EditorAssetFolder[];
+  assets: EditorAsset[];
+  folderId: string;
+  defaultFolderId: string;
+}) {
+  return {
+    folders: folders.filter((folder) => folder.id !== folderId),
+    assets: assets.map((asset) =>
+      asset.folderId === folderId
+        ? {
+            ...asset,
+            folderId: defaultFolderId,
+          }
+        : asset,
+    ),
+  };
+}
+
+export function toggleAssetSelection(
+  selectedAssetIds: Set<string>,
+  assetId: string,
+) {
+  const nextIds = new Set(selectedAssetIds);
+  if (nextIds.has(assetId)) {
+    nextIds.delete(assetId);
+  } else {
+    nextIds.add(assetId);
+  }
+  return nextIds;
+}
+
+export function resolveAllAssetSelection({
+  allSelectableAssetsSelected,
+  selectableAssets,
+}: {
+  allSelectableAssetsSelected: boolean;
+  selectableAssets: EditorAsset[];
+}) {
+  return allSelectableAssetsSelected
+    ? new Set<string>()
+    : new Set(selectableAssets.map((asset) => asset.id));
+}
+
+export function removeSelectedAssets(
+  assets: EditorAsset[],
+  selectedAssetIds: Set<string>,
+) {
+  const deletedAssets = assets.filter((asset) => selectedAssetIds.has(asset.id));
+  return {
+    assets: assets.filter((asset) => !selectedAssetIds.has(asset.id)),
+    deletedAssets,
+  };
+}
+
+export function moveAssetToFolderLocally(
+  assets: EditorAsset[],
+  assetId: string,
+  folderId: string,
+) {
+  return assets.map((asset) =>
+    asset.id === assetId
+      ? {
+          ...asset,
+          folderId,
+        }
+      : asset,
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx b/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx
new file mode 100644
index 000000000..dee2ab8cf
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetLibraryPanelView.tsx
@@ -0,0 +1,279 @@
+import {
+  Check,
+  CheckSquare,
+  Folder,
+  Square,
+  Trash2,
+  X,
+} from 'lucide-react';
+import type {
+  Dispatch,
+  PointerEvent as ReactPointerEvent,
+  RefObject,
+  SetStateAction,
+} from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformBatchActionToolbar } from '../common/PlatformBatchActionToolbar';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import { ImageCanvasAssetFolderSectionView } from './ImageCanvasAssetFolderSectionView';
+import type {
+  AssetMarqueeState,
+  AssetPointerDragState,
+  EditorAsset,
+  EditorAssetFolder,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+
+export type GroupedEditorAssetFolder = EditorAssetFolder & {
+  assets: EditorAsset[];
+};
+
+export type UploadFilesOptions = {
+  folderId?: string;
+  canvasPoint?: { x: number; y: number };
+  addToCanvas?: boolean;
+};
+
+export type ImageCanvasAssetLibraryPanelViewProps = {
+  assetListRef: RefObject<HTMLDivElement | null>;
+  assetPointerDragRef: { current: AssetPointerDragState | null };
+  suppressAssetClickRef: { current: boolean };
+  groupedAssets: GroupedEditorAssetFolder[];
+  assetFolders: EditorAssetFolder[];
+  isAssetSelectionMode: boolean;
+  selectedAssetIds: Set<string>;
+  assetMoveDropFolderId: string | null;
+  pinnedAssetMoveFolderId: string | null;
+  creatingFolder: boolean;
+  newFolderName: string;
+  renamingFolder: { folderId: string; value: string } | null;
+  renamingAsset: { assetId: string; value: string } | null;
+  allSelectableAssetsSelected: boolean;
+  assetMarquee: AssetMarqueeState | null;
+  setCreatingFolder: Dispatch<SetStateAction<boolean>>;
+  setNewFolderName: Dispatch<SetStateAction<string>>;
+  setRenamingFolder: Dispatch<
+    SetStateAction<{ folderId: string; value: string } | null>
+  >;
+  setRenamingAsset: Dispatch<
+    SetStateAction<{ assetId: string; value: string } | null>
+  >;
+  setActiveUploadFolderId: Dispatch<SetStateAction<string>>;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setSelectedAssetIds: Dispatch<SetStateAction<Set<string>>>;
+  onAssetMarqueePointerDown: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  onAssetMarqueePointerMove: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  onAssetMarqueePointerUp: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  addUploadedFiles: (files: FileList | File[], options?: UploadFilesOptions) => void;
+  requestUpload: (target: UploadTarget) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  commitNewAssetFolder: () => void | Promise<void>;
+  toggleAssetFolder: (folderId: string) => void;
+  startRenamingFolder: (folder: EditorAssetFolder) => void;
+  commitFolderRename: (folder: EditorAssetFolder) => void;
+  deleteAssetFolder: (folder: EditorAssetFolder) => void;
+  startRenamingAsset: (asset: EditorAsset) => void;
+  commitAssetRename: (asset: EditorAsset) => void;
+  deleteUploadedAsset: (asset: EditorAsset) => void;
+  toggleAssetSelected: (assetId: string) => void;
+  addAssetLayer: (asset: EditorAsset) => void;
+  toggleAllAssetsSelected: () => void;
+  deleteSelectedAssets: () => void;
+  closeAssetSelectionMode: () => void;
+};
+
+export function ImageCanvasAssetLibraryPanelView({
+  assetListRef,
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  groupedAssets,
+  assetFolders,
+  isAssetSelectionMode,
+  selectedAssetIds,
+  assetMoveDropFolderId,
+  pinnedAssetMoveFolderId,
+  creatingFolder,
+  newFolderName,
+  renamingFolder,
+  renamingAsset,
+  allSelectableAssetsSelected,
+  assetMarquee,
+  setCreatingFolder,
+  setNewFolderName,
+  setRenamingFolder,
+  setRenamingAsset,
+  setActiveUploadFolderId,
+  setUploadDropTarget,
+  setAssetPointerDrag,
+  setSelectedAssetIds,
+  onAssetMarqueePointerDown,
+  onAssetMarqueePointerMove,
+  onAssetMarqueePointerUp,
+  updateAssetMoveDropFolder,
+  addUploadedFiles,
+  requestUpload,
+  moveAssetToFolder,
+  commitNewAssetFolder,
+  toggleAssetFolder,
+  startRenamingFolder,
+  commitFolderRename,
+  deleteAssetFolder,
+  startRenamingAsset,
+  commitAssetRename,
+  deleteUploadedAsset,
+  toggleAssetSelected,
+  addAssetLayer,
+  toggleAllAssetsSelected,
+  deleteSelectedAssets,
+  closeAssetSelectionMode,
+}: ImageCanvasAssetLibraryPanelViewProps) {
+  return (
+    <div
+      ref={assetListRef}
+      className="image-canvas-editor__asset-list"
+      onPointerDown={onAssetMarqueePointerDown}
+      onPointerMove={onAssetMarqueePointerMove}
+      onPointerUp={onAssetMarqueePointerUp}
+      onPointerCancel={onAssetMarqueePointerUp}
+    >
+      {pinnedAssetMoveFolderId ? (
+        <div
+          className="image-canvas-editor__asset-folder-sticky-target"
+          aria-hidden="true"
+        >
+          <Folder className="h-4 w-4" />
+          <span>
+            {assetFolders.find((folder) => folder.id === pinnedAssetMoveFolderId)
+              ?.label ?? '目标文件夹'}
+          </span>
+        </div>
+      ) : null}
+      {creatingFolder ? (
+        <form
+          className="image-canvas-editor__folder-create"
+          onSubmit={(event) => {
+            event.preventDefault();
+            void commitNewAssetFolder();
+          }}
+        >
+          <PlatformTextField
+            aria-label="素材文件夹名称"
+            value={newFolderName}
+            autoFocus
+            size="xs"
+            density="compact"
+            className="image-canvas-editor__folder-create-input"
+            onChange={(event) => setNewFolderName(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Escape') {
+                event.preventDefault();
+                setCreatingFolder(false);
+                setNewFolderName('');
+              }
+            }}
+          />
+          <EditorIconButton type="submit" label="保存素材文件夹" icon={Check} />
+          <EditorIconButton
+            label="取消新建素材文件夹"
+            icon={X}
+            onClick={() => {
+              setCreatingFolder(false);
+              setNewFolderName('');
+            }}
+          />
+        </form>
+      ) : null}
+      {groupedAssets.map((folder) => (
+        <ImageCanvasAssetFolderSectionView
+          key={folder.id}
+          folder={folder}
+          assetPointerDragRef={assetPointerDragRef}
+          suppressAssetClickRef={suppressAssetClickRef}
+          isAssetSelectionMode={isAssetSelectionMode}
+          selectedAssetIds={selectedAssetIds}
+          assetMoveDropFolderId={assetMoveDropFolderId}
+          renamingFolder={renamingFolder}
+          renamingAsset={renamingAsset}
+          setRenamingFolder={setRenamingFolder}
+          setRenamingAsset={setRenamingAsset}
+          setActiveUploadFolderId={setActiveUploadFolderId}
+          setUploadDropTarget={setUploadDropTarget}
+          setAssetPointerDrag={setAssetPointerDrag}
+          setSelectedAssetIds={setSelectedAssetIds}
+          updateAssetMoveDropFolder={updateAssetMoveDropFolder}
+          addUploadedFiles={addUploadedFiles}
+          requestUpload={requestUpload}
+          moveAssetToFolder={moveAssetToFolder}
+          toggleAssetFolder={toggleAssetFolder}
+          startRenamingFolder={startRenamingFolder}
+          commitFolderRename={commitFolderRename}
+          deleteAssetFolder={deleteAssetFolder}
+          startRenamingAsset={startRenamingAsset}
+          commitAssetRename={commitAssetRename}
+          deleteUploadedAsset={deleteUploadedAsset}
+          toggleAssetSelected={toggleAssetSelected}
+          addAssetLayer={addAssetLayer}
+        />
+      ))}
+      {isAssetSelectionMode ? (
+        <PlatformBatchActionToolbar
+          className="image-canvas-editor__asset-batch-toolbar"
+          label="素材批量操作"
+        >
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            onClick={toggleAllAssetsSelected}
+          >
+            {allSelectableAssetsSelected ? (
+              <CheckSquare className="h-4 w-4" />
+            ) : (
+              <Square className="h-4 w-4" />
+            )}
+            {selectedAssetIds.size > 0
+              ? `${allSelectableAssetsSelected ? '取消全选' : '全选'} · 已选 ${selectedAssetIds.size}`
+              : '全选'}
+          </PlatformActionButton>
+          <PlatformActionButton
+            tone="warning"
+            size="sm"
+            disabled={selectedAssetIds.size === 0}
+            onClick={deleteSelectedAssets}
+          >
+            <Trash2 className="h-4 w-4" />
+            删除
+          </PlatformActionButton>
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            onClick={closeAssetSelectionMode}
+          >
+            取消
+          </PlatformActionButton>
+        </PlatformBatchActionToolbar>
+      ) : null}
+      {assetMarquee ? (
+        <div
+          className="image-canvas-editor__asset-marquee"
+          aria-hidden="true"
+          style={{
+            left: Math.min(assetMarquee.startX, assetMarquee.currentX),
+            top: Math.min(assetMarquee.startY, assetMarquee.currentY),
+            width: Math.abs(assetMarquee.currentX - assetMarquee.startX),
+            height: Math.abs(assetMarquee.currentY - assetMarquee.startY),
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.test.tsx b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
new file mode 100644
index 000000000..6de452d65
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetRowView.test.tsx
@@ -0,0 +1,167 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { EditorAsset } from './ImageCanvasEditorTypes';
+import { ImageCanvasAssetRowView } from './ImageCanvasAssetRowView';
+
+function createAsset(overrides: Partial<EditorAsset> = {}): EditorAsset {
+  return {
+    id: 'asset-1',
+    label: '账号素材A',
+    src: '/creation-type-references/puzzle.webp',
+    width: 640,
+    height: 512,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function renderAssetRow({
+  asset = createAsset(),
+  isAssetSelectionMode = false,
+  selectedAssetIds = new Set<string>(),
+  renamingAsset = null,
+  suppressAssetClick = false,
+  addAssetLayer = vi.fn(),
+  toggleAssetSelected = vi.fn(),
+  commitAssetRename = vi.fn(),
+}: {
+  asset?: EditorAsset;
+  isAssetSelectionMode?: boolean;
+  selectedAssetIds?: Set<string>;
+  renamingAsset?: { assetId: string; value: string } | null;
+  suppressAssetClick?: boolean;
+  addAssetLayer?: (asset: EditorAsset) => void;
+  toggleAssetSelected?: (assetId: string) => void;
+  commitAssetRename?: (asset: EditorAsset) => void;
+} = {}) {
+  const props = {
+    asset,
+    assetPointerDragRef: { current: null },
+    suppressAssetClickRef: { current: suppressAssetClick },
+    isAssetSelectionMode,
+    selectedAssetIds,
+    renamingAsset,
+    setRenamingAsset: vi.fn(),
+    setUploadDropTarget: vi.fn(),
+    setAssetPointerDrag: vi.fn(),
+    setSelectedAssetIds: vi.fn(),
+    updateAssetMoveDropFolder: vi.fn(),
+    addUploadedFiles: vi.fn(),
+    moveAssetToFolder: vi.fn(),
+    startRenamingAsset: vi.fn(),
+    commitAssetRename,
+    deleteUploadedAsset: vi.fn(),
+    toggleAssetSelected,
+    addAssetLayer,
+  };
+
+  render(<ImageCanvasAssetRowView {...props} />);
+  return props;
+}
+
+describe('ImageCanvasAssetRowView', () => {
+  it('adds the asset to the canvas in normal mode', () => {
+    const addAssetLayer = vi.fn();
+    const asset = createAsset();
+    renderAssetRow({ asset, addAssetLayer });
+
+    fireEvent.click(screen.getByRole('button', { name: '添加账号素材A' }));
+
+    expect(addAssetLayer).toHaveBeenCalledWith(asset);
+  });
+
+  it('selects the asset instead of adding it in selection mode', () => {
+    const addAssetLayer = vi.fn();
+    const toggleAssetSelected = vi.fn();
+    renderAssetRow({
+      isAssetSelectionMode: true,
+      addAssetLayer,
+      toggleAssetSelected,
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '选择素材账号素材A' }));
+
+    expect(toggleAssetSelected).toHaveBeenCalledWith('asset-1');
+    expect(addAssetLayer).not.toHaveBeenCalled();
+  });
+
+  it('renders rename input and commits with Enter', () => {
+    const commitAssetRename = vi.fn();
+    renderAssetRow({
+      renamingAsset: { assetId: 'asset-1', value: '主视觉素材' },
+      commitAssetRename,
+    });
+
+    const input = screen.getByLabelText('重命名素材账号素材A');
+    fireEvent.keyDown(input, { key: 'Enter' });
+
+    expect(input.className).toContain('platform-text-field');
+    expect(input.className).toContain('image-canvas-editor__asset-rename-input');
+    expect(commitAssetRename).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'asset-1' }),
+    );
+  });
+
+  it('keeps uploading assets disabled and shows progress', () => {
+    const addAssetLayer = vi.fn();
+    renderAssetRow({
+      asset: createAsset({
+        uploadStatus: 'uploading',
+        uploadProgress: 42,
+        uploadMessage: '正在上传',
+      }),
+      addAssetLayer,
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '上传中账号素材A' }));
+
+    expect(addAssetLayer).not.toHaveBeenCalled();
+    expect(screen.getAllByText('正在上传').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('42%').length).toBeGreaterThan(0);
+    expect(
+      screen.getByLabelText('素材账号素材A上传进度').getAttribute('value'),
+    ).toBe('42');
+  });
+
+  it('uses icon thumbnails for audio assets instead of rendering media as images', () => {
+    renderAssetRow({
+      asset: createAsset({
+        label: '胜利音效.mp3',
+        src: '/generated-character-drafts/editor/asset-library/audio/胜利音效.mp3',
+        mediaType: 'audio',
+      }),
+    });
+
+    expect(screen.getByText('音频')).toBeTruthy();
+    expect(screen.queryByRole('img', { name: '素材：胜利音效.mp3' })).toBeNull();
+    expect(
+      document.querySelector('.image-canvas-editor__asset-media-overlay'),
+    ).toBeTruthy();
+    expect(
+      document.querySelector('.image-canvas-editor__media-preview--audio'),
+    ).toBeTruthy();
+  });
+
+  it('uses a stable visual preview for video asset cards without image thumbnails', () => {
+    renderAssetRow({
+      asset: createAsset({
+        label: '生成视频.mp4',
+        src: '/generated-character-drafts/editor/asset-library/video/demo.mp4',
+        mediaType: 'video',
+      }),
+    });
+
+    expect(screen.getByText('视频')).toBeTruthy();
+    expect(screen.queryByRole('img', { name: '素材：生成视频.mp4' })).toBeNull();
+    expect(
+      document.querySelector('.image-canvas-editor__media-preview--video')
+        ?.className,
+    ).toContain('image-canvas-editor__media-preview--variant-');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasAssetRowView.tsx b/src/components/image-editor/ImageCanvasAssetRowView.tsx
new file mode 100644
index 000000000..6a738434b
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasAssetRowView.tsx
@@ -0,0 +1,354 @@
+import { Check, Music2, Pencil, Trash2, Video, X } from 'lucide-react';
+import type { Dispatch, SetStateAction } from 'react';
+
+import { PlatformTextField } from '../common/PlatformTextField';
+import {
+  EditorIconButton,
+  SidebarMediaItem,
+} from './ImageCanvasEditorPrimitives';
+import {
+  ASSET_DRAG_MIME_TYPE,
+  clamp,
+  getDraggedAssetId,
+  hasDataTransferType,
+} from './ImageCanvasEditorModel';
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+import {
+  getCanvasMediaPreviewClassName,
+  getCanvasMediaPreviewMarker,
+} from './ImageCanvasMediaModel';
+import type { UploadFilesOptions } from './ImageCanvasAssetLibraryPanelView';
+
+export type ImageCanvasAssetRowViewProps = {
+  asset: EditorAsset;
+  assetPointerDragRef: { current: AssetPointerDragState | null };
+  suppressAssetClickRef: { current: boolean };
+  isAssetSelectionMode: boolean;
+  selectedAssetIds: Set<string>;
+  renamingAsset: { assetId: string; value: string } | null;
+  setRenamingAsset: Dispatch<
+    SetStateAction<{ assetId: string; value: string } | null>
+  >;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setSelectedAssetIds: Dispatch<SetStateAction<Set<string>>>;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  addUploadedFiles: (files: FileList | File[], options?: UploadFilesOptions) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  startRenamingAsset: (asset: EditorAsset) => void;
+  commitAssetRename: (asset: EditorAsset) => void;
+  deleteUploadedAsset: (asset: EditorAsset) => void;
+  toggleAssetSelected: (assetId: string) => void;
+  addAssetLayer: (asset: EditorAsset) => void;
+};
+
+export function ImageCanvasAssetRowView({
+  asset,
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  isAssetSelectionMode,
+  selectedAssetIds,
+  renamingAsset,
+  setRenamingAsset,
+  setUploadDropTarget,
+  setAssetPointerDrag,
+  setSelectedAssetIds,
+  updateAssetMoveDropFolder,
+  addUploadedFiles,
+  moveAssetToFolder,
+  startRenamingAsset,
+  commitAssetRename,
+  deleteUploadedAsset,
+  toggleAssetSelected,
+  addAssetLayer,
+}: ImageCanvasAssetRowViewProps) {
+  const isRenaming = renamingAsset?.assetId === asset.id;
+  const isUploadingAsset = asset.uploadStatus === 'uploading';
+  const isFailedUpload = asset.uploadStatus === 'failed';
+  const uploadProgress = clamp(asset.uploadProgress ?? 0, 0, 100);
+  const mediaPreviewMarker = getCanvasMediaPreviewMarker(asset);
+  const mediaPreviewClassName =
+    getCanvasMediaPreviewClassName(mediaPreviewMarker);
+  const mediaDetail =
+    asset.mediaType === 'audio'
+      ? '音频'
+      : asset.mediaType === 'video'
+        ? '视频'
+        : `${asset.width} x ${asset.height}`;
+  const mediaOverlay =
+    asset.mediaType === 'audio' ? (
+      <div
+        className={`image-canvas-editor__asset-media-overlay ${mediaPreviewClassName}`}
+      >
+        <Music2 className="h-5 w-5" />
+      </div>
+    ) : asset.mediaType === 'video' ? (
+      <div
+        className={`image-canvas-editor__asset-media-overlay ${mediaPreviewClassName}`}
+      >
+        <Video className="h-5 w-5" />
+      </div>
+    ) : undefined;
+  const titleNode = isRenaming ? (
+    <PlatformTextField
+      aria-label={`重命名素材${asset.label}`}
+      value={renamingAsset.value}
+      autoFocus
+      size="xs"
+      density="compact"
+      className="image-canvas-editor__asset-rename-input"
+      onChange={(event) =>
+        setRenamingAsset({
+          assetId: asset.id,
+          value: event.target.value,
+        })
+      }
+      onKeyDown={(event) => {
+        if (event.key === 'Enter') {
+          event.preventDefault();
+          commitAssetRename(asset);
+        }
+        if (event.key === 'Escape') {
+          event.preventDefault();
+          setRenamingAsset(null);
+        }
+      }}
+    />
+  ) : undefined;
+  const actions = isUploadingAsset ? (
+    <div className="image-canvas-editor__asset-upload-status">
+      <span>{asset.uploadMessage ?? '上传中'}</span>
+      <strong>{Math.round(uploadProgress)}%</strong>
+    </div>
+  ) : isRenaming ? (
+    <div className="image-canvas-editor__asset-actions">
+      <EditorIconButton
+        label={`保存素材${asset.label}名称`}
+        title="保存"
+        icon={Check}
+        onClick={() => commitAssetRename(asset)}
+      />
+      <EditorIconButton
+        label={`取消重命名素材${asset.label}`}
+        title="取消"
+        icon={X}
+        onClick={() => setRenamingAsset(null)}
+      />
+    </div>
+  ) : (
+    <div className="image-canvas-editor__asset-actions">
+      <EditorIconButton
+        label={`重命名素材${asset.label}`}
+        title="重命名"
+        icon={Pencil}
+        onClick={() => startRenamingAsset(asset)}
+      />
+      {asset.sourceKind === 'uploaded' ? (
+        <EditorIconButton
+          label={`删除素材${asset.label}`}
+          title="删除"
+          icon={Trash2}
+          onClick={() => deleteUploadedAsset(asset)}
+        />
+      ) : null}
+    </div>
+  );
+
+  return (
+    <div data-asset-id={asset.id}>
+      <SidebarMediaItem
+        title={asset.label}
+        detail={mediaDetail}
+        imageAlt={`素材：${asset.label}`}
+        primaryLabel={
+          isUploadingAsset
+            ? `上传中${asset.label}`
+            : isFailedUpload
+              ? `上传失败${asset.label}`
+              : isAssetSelectionMode
+                ? `选择素材${asset.label}`
+                : `添加${asset.label}`
+        }
+        onPrimaryClick={() => {
+          if (isUploadingAsset || isFailedUpload) {
+            return;
+          }
+          if (suppressAssetClickRef.current) {
+            return;
+          }
+          if (isAssetSelectionMode) {
+            toggleAssetSelected(asset.id);
+            return;
+          }
+          addAssetLayer(asset);
+        }}
+        selected={selectedAssetIds.has(asset.id)}
+        rowClassName={[
+          'image-canvas-editor__asset-row',
+          isUploadingAsset ? 'image-canvas-editor__asset-row--uploading' : '',
+          isFailedUpload
+            ? 'image-canvas-editor__asset-row--upload-failed'
+            : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        primaryClassName="image-canvas-editor__asset-button"
+        thumbnailClassName="image-canvas-editor__asset-thumb"
+        metaClassName="image-canvas-editor__asset-meta"
+        imageSrc={
+          asset.mediaType === 'image'
+            ? asset.src
+            : (asset.thumbnailSrc ?? '')
+        }
+        titleNode={
+          isUploadingAsset || isFailedUpload ? <span>{asset.label}</span> : titleNode
+        }
+        actions={actions}
+        draggable={!isRenaming && !isUploadingAsset && !isFailedUpload}
+        previewOverlay={
+          isUploadingAsset ? (
+            <div className="image-canvas-editor__asset-upload-overlay">
+              <span>上传中</span>
+            </div>
+          ) : (
+            mediaOverlay
+          )
+        }
+        footerNode={
+          isUploadingAsset || isFailedUpload ? (
+            <div className="image-canvas-editor__asset-upload-progress">
+              <div>
+                <span>
+                  {isFailedUpload
+                    ? (asset.uploadMessage ?? '上传失败')
+                    : (asset.uploadMessage ?? '上传中')}
+                </span>
+                <strong>{Math.round(uploadProgress)}%</strong>
+              </div>
+              <progress
+                aria-label={`素材${asset.label}上传进度`}
+                max={100}
+                value={uploadProgress}
+              />
+            </div>
+          ) : undefined
+        }
+        onDragStart={(event) => {
+          if (isRenaming || isUploadingAsset || isFailedUpload) {
+            event.preventDefault();
+            return;
+          }
+          if (assetPointerDragRef.current?.assetId === asset.id) {
+            event.preventDefault();
+            return;
+          }
+          event.dataTransfer.effectAllowed = 'move';
+          event.dataTransfer.setData(ASSET_DRAG_MIME_TYPE, asset.id);
+          event.dataTransfer.setData('text/plain', asset.label);
+          event.dataTransfer.setData('text/uri-list', asset.src);
+          updateAssetMoveDropFolder(asset.folderId);
+        }}
+        onDragEnd={() => {
+          setUploadDropTarget(null);
+          updateAssetMoveDropFolder(null);
+        }}
+        onPointerDown={(event) => {
+          if (event.button !== 0) {
+            return;
+          }
+          const target = event.target as HTMLElement;
+          if (isAssetSelectionMode) {
+            if (target.closest('button')) {
+              return;
+            }
+            return;
+          }
+          if (
+            isRenaming ||
+            isUploadingAsset ||
+            isFailedUpload ||
+            target.closest('input, textarea, select')
+          ) {
+            return;
+          }
+          const primaryAssetButton = target.closest(
+            '.image-canvas-editor__asset-button',
+          );
+          if (target.closest('button') && !primaryAssetButton) {
+            return;
+          }
+          const nextDrag: AssetPointerDragState = {
+            pointerId: event.pointerId,
+            assetId: asset.id,
+            startClientX: event.clientX,
+            startClientY: event.clientY,
+            currentClientX: event.clientX,
+            currentClientY: event.clientY,
+            active: false,
+            dropFolderId: null,
+          };
+          if (!primaryAssetButton) {
+            try {
+              event.currentTarget.setPointerCapture?.(event.pointerId);
+            } catch {
+              // 自动化环境可能没有 active pointer，拖拽状态仍可走 window 事件完成。
+            }
+            event.preventDefault();
+          }
+          event.stopPropagation();
+          assetPointerDragRef.current = nextDrag;
+          setAssetPointerDrag(nextDrag);
+        }}
+        onPointerEnter={(event) => {
+          if (isAssetSelectionMode && event.buttons === 1) {
+            setSelectedAssetIds((currentIds) => {
+              const nextIds = new Set(currentIds);
+              nextIds.add(asset.id);
+              return nextIds;
+            });
+          }
+        }}
+        onDragOver={(event) => {
+          if (hasDataTransferType(event.dataTransfer, ASSET_DRAG_MIME_TYPE)) {
+            event.preventDefault();
+            event.stopPropagation();
+            setUploadDropTarget(null);
+            updateAssetMoveDropFolder(asset.folderId);
+            event.dataTransfer.dropEffect = 'move';
+            return;
+          }
+          if (hasDataTransferType(event.dataTransfer, 'Files')) {
+            event.preventDefault();
+            event.stopPropagation();
+            setUploadDropTarget('assets');
+            event.dataTransfer.dropEffect = 'copy';
+          }
+        }}
+        onDrop={(event) => {
+          const movingAssetId = getDraggedAssetId(event.dataTransfer);
+          if (movingAssetId) {
+            event.preventDefault();
+            event.stopPropagation();
+            setUploadDropTarget(null);
+            updateAssetMoveDropFolder(null);
+            moveAssetToFolder(movingAssetId, asset.folderId);
+            return;
+          }
+          if (!event.dataTransfer.files.length) {
+            return;
+          }
+          event.preventDefault();
+          event.stopPropagation();
+          setUploadDropTarget(null);
+          updateAssetMoveDropFolder(null);
+          addUploadedFiles(event.dataTransfer.files, {
+            folderId: asset.folderId,
+          });
+        }}
+      />
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx
new file mode 100644
index 000000000..afa372f84
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.test.tsx
@@ -0,0 +1,213 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { createRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ImageCanvasBasicGenerationComposerView } from './ImageCanvasBasicGenerationComposerView';
+import type {
+  GenerateDialogState,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+
+function createDialog(
+  patch: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'generate',
+    prompt: '初始提示',
+    status: 'idle',
+    generationReferences: [],
+    imageModel: 'gemini-3.1-flash-image-preview',
+    aspectRatio: '16:9',
+    imageSize: '1K',
+    ...patch,
+  };
+}
+
+function BasicGenerationHarness({
+  initialDialog = createDialog(),
+  onRequestUpload = vi.fn(),
+  onSubmit = vi.fn(),
+}: {
+  initialDialog?: GenerateDialogState;
+  onRequestUpload?: (target: UploadTarget) => void;
+  onSubmit?: (dialog: GenerateDialogState) => void;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+  const [isReferenceMenuOpen, setIsReferenceMenuOpen] = useState(false);
+  const [isPickingReference, setIsPickingReference] = useState(false);
+  const generationReferenceButtonRef = createRef<HTMLButtonElement>();
+
+  return dialog ? (
+    <div>
+      <ImageCanvasBasicGenerationComposerView
+        dialog={dialog}
+        style={{ left: 10, top: 20 }}
+        setGenerateDialog={setDialog}
+        generationReferenceButtonRef={generationReferenceButtonRef}
+        isGenerationReferenceMenuOpen={isReferenceMenuOpen}
+        setIsGenerationReferenceMenuOpen={setIsReferenceMenuOpen}
+        setIsPickingGenerationReferenceFromCanvas={setIsPickingReference}
+        renderEditorPortal={(node) => node}
+        buildPortalMenuStyle={() => ({ position: 'fixed', left: 0, top: 0 })}
+        onRequestUpload={onRequestUpload}
+        onToggleReferenceMenu={() => setIsReferenceMenuOpen((open) => !open)}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="当前提示词">{dialog.prompt}</output>
+      <output aria-label="当前比例">{dialog.aspectRatio}</output>
+      <output aria-label="当前尺寸">{dialog.imageSize}</output>
+      <output aria-label="当前模型">{dialog.imageModel}</output>
+      <output aria-label="当前状态">{dialog.status}</output>
+      <output aria-label="当前错误">{dialog.errorMessage ?? '-'}</output>
+      <output aria-label="选择参考图">{String(isPickingReference)}</output>
+    </div>
+  ) : null;
+}
+
+describe('ImageCanvasBasicGenerationComposerView', () => {
+  it('updates prompt, clears failed state, uploads references and submits', () => {
+    const requestUpload = vi.fn();
+    const submitGeneration = vi.fn();
+    render(
+      <BasicGenerationHarness
+        initialDialog={createDialog({
+          status: 'failed',
+          errorMessage: '生成失败',
+        })}
+        onRequestUpload={requestUpload}
+        onSubmit={submitGeneration}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '新的提示' },
+    });
+    const panel = screen.getByRole('dialog', { name: '生成图片' });
+    fireEvent.click(within(panel).getByRole('button', { name: '添加参考图' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect(screen.getByLabelText('当前提示词').textContent).toBe('新的提示');
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+    expect(requestUpload).toHaveBeenCalledWith('generation-reference');
+    expect(submitGeneration).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: '新的提示', status: 'idle' }),
+    );
+  });
+
+  it('keeps references on the first row and appends a new add-reference entry', () => {
+    render(
+      <BasicGenerationHarness
+        initialDialog={createDialog({
+          generationReferences: [
+            {
+              id: 'ref-a',
+              label: '参考图A',
+              src: 'data:image/png;base64,cmVmQQ==',
+            },
+            {
+              id: 'ref-b',
+              label: '参考图B',
+              src: 'data:image/png;base64,cmVmQg==',
+            },
+          ],
+        })}
+      />,
+    );
+
+    const panel = screen.getByRole('dialog', { name: '生成图片' });
+    const strip = panel.querySelector('.image-canvas-editor__reference-strip');
+
+    expect(strip).toBeTruthy();
+    expect(within(strip as HTMLElement).getByText('参考图A')).toBeTruthy();
+    expect(within(strip as HTMLElement).getByText('参考图B')).toBeTruthy();
+    expect(
+      within(strip as HTMLElement).getByRole('button', { name: '添加参考图' }),
+    ).toBeTruthy();
+  });
+
+  it('removes an existing reference from its hover delete button', () => {
+    render(
+      <BasicGenerationHarness
+        initialDialog={createDialog({
+          generationReferences: [
+            {
+              id: 'ref-a',
+              label: '参考图A',
+              src: 'data:image/png;base64,cmVmQQ==',
+            },
+          ],
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '删除参考图A' }));
+
+    expect(screen.queryByText('参考图A')).toBeNull();
+  });
+
+  it('shows only current image options and opens upward option panels', () => {
+    render(<BasicGenerationHarness />);
+
+    const panel = screen.getByRole('dialog', { name: '生成图片' });
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: '生成图片尺寸 16:9·1K',
+      }),
+    );
+    const dimensionPanel = screen.getByRole('menu', {
+      name: '生成图片尺寸选项',
+    });
+    expect(within(dimensionPanel).getByText('比例')).toBeTruthy();
+    fireEvent.click(within(dimensionPanel).getByRole('button', { name: '2K' }));
+
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('2K');
+
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: '生成图片模型 nanobanana2',
+      }),
+    );
+    const modelPanel = screen.getByRole('menu', { name: '生成图片模型选项' });
+    fireEvent.click(
+      within(modelPanel).getByRole('button', { name: /gpt-image-2/ }),
+    );
+
+    expect(screen.getByLabelText('当前模型').textContent).toBe('gpt-image-2');
+    const submitButton = within(panel).getByRole('button', { name: '生成' });
+    expect(submitButton.textContent).toBe('生成20泥点');
+  });
+
+  it('clicks the parent generation panel to collapse an opened option panel', () => {
+    render(<BasicGenerationHarness />);
+
+    const panel = screen.getByRole('dialog', { name: '生成图片' });
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: '生成图片尺寸 16:9·1K',
+      }),
+    );
+    expect(
+      screen.getByRole('menu', { name: '生成图片尺寸选项' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('textbox', { name: '生成提示词' }));
+
+    expect(
+      screen.queryByRole('menu', { name: '生成图片尺寸选项' }),
+    ).toBeNull();
+  });
+
+  it('does not render a standalone close button', () => {
+    render(<BasicGenerationHarness />);
+
+    expect(
+      screen.queryByRole('button', { name: '关闭生成图片' }),
+    ).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx
new file mode 100644
index 000000000..9a83ecc9d
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasBasicGenerationComposerView.tsx
@@ -0,0 +1,237 @@
+import { ImageIcon } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import type {
+  CharacterReferenceImage,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import {
+  calculateEditorImageGenerationPrice,
+} from './ImageCanvasGenerationModel';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasBasicGenerationComposerViewProps = {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  generationReferenceButtonRef?: RefObject<HTMLButtonElement | null>;
+  isGenerationReferenceMenuOpen?: boolean;
+  setIsGenerationReferenceMenuOpen?: Dispatch<SetStateAction<boolean>>;
+  setIsPickingGenerationReferenceFromCanvas?: Dispatch<SetStateAction<boolean>>;
+  renderEditorPortal?: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle?: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onRequestUpload: (target: 'generation-reference') => void;
+  onToggleReferenceMenu?: () => void;
+  onRememberImageModel?: (model: string) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+function resetFailedDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function ReferenceChip({
+  reference,
+  index,
+  onRemove,
+}: {
+  reference: CharacterReferenceImage;
+  index: number;
+  onRemove: () => void;
+}) {
+  const label = reference.label || `参考图${index + 1}`;
+  return (
+    <ImageCanvasReferenceSlot
+      tone="default"
+      icon={<ImageIcon className="h-4 w-4" aria-hidden="true" />}
+      imageSrc={reference.src}
+      label={label}
+      ariaLabel={label}
+      title={reference.label}
+      onRemove={onRemove}
+      removeLabel={`删除${label}`}
+    />
+  );
+}
+
+export function ImageCanvasBasicGenerationComposerView({
+  dialog,
+  style,
+  setGenerateDialog,
+  generationReferenceButtonRef,
+  isGenerationReferenceMenuOpen = false,
+  setIsGenerationReferenceMenuOpen,
+  setIsPickingGenerationReferenceFromCanvas,
+  renderEditorPortal = (node) => node,
+  buildPortalMenuStyle = () => ({}),
+  onRequestUpload,
+  onToggleReferenceMenu,
+  onRememberImageModel = () => {},
+  onSubmit,
+}: ImageCanvasBasicGenerationComposerViewProps) {
+  const references = dialog.generationReferences ?? [];
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isGenerationReferenceMenuOpen,
+    boundaryRefs: [generationReferenceButtonRef],
+    onDismiss: () => setIsGenerationReferenceMenuOpen?.(false),
+  });
+
+  return (
+    <>
+      <form
+        className="image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image"
+        style={style}
+        role="dialog"
+        aria-label="生成图片"
+        onPointerDown={(event) => event.stopPropagation()}
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (dialog.status !== 'generating') {
+            onSubmit(dialog);
+          }
+        }}
+      >
+      <div className="image-canvas-editor__reference-strip">
+        {references.map((reference, index) => (
+          <ReferenceChip
+            key={reference.id}
+            reference={reference}
+            index={index}
+            onRemove={() =>
+              setGenerateDialog((currentDialog) =>
+                currentDialog
+                  ? {
+                      ...resetFailedDialogStatus(currentDialog),
+                      generationReferences: (
+                        currentDialog.generationReferences ?? []
+                      ).filter((item) => item.id !== reference.id),
+                    }
+                  : currentDialog,
+              )
+            }
+          />
+        ))}
+        <ImageCanvasReferenceSlot
+          buttonRef={generationReferenceButtonRef}
+          tone="default"
+          icon={<ImageIcon className="h-4 w-4" aria-hidden="true" />}
+          label="参考图"
+          ariaLabel="添加参考图"
+          disabled={dialog.status === 'generating'}
+          isAdd
+          onClick={() => onToggleReferenceMenu?.()}
+        />
+      </div>
+      <PlatformTextField
+        variant="textarea"
+        aria-label="生成提示词"
+        value={dialog.prompt}
+        disabled={dialog.status === 'generating'}
+        placeholder="今天想生成什么画面？"
+        size="sm"
+        density="compact"
+        className="image-canvas-editor__generation-prompt"
+        onChange={(event) =>
+          setGenerateDialog((currentDialog) =>
+            currentDialog
+              ? {
+                  ...resetFailedDialogStatus(currentDialog),
+                  prompt: event.target.value,
+                }
+              : currentDialog,
+          )
+        }
+      />
+      <div className="image-canvas-editor__generation-composer-footer">
+        <ImageCanvasGenerationImageOptionsView
+          dialog={dialog}
+          setGenerateDialog={setGenerateDialog}
+          includeDimensions
+          onRememberImageModel={onRememberImageModel}
+          optionLabelPrefix="生成图片"
+          cost={calculateEditorImageGenerationPrice({
+            model: dialog.imageModel,
+          })}
+          submitLabel="生成"
+          submitAriaLabel="生成"
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+        />
+      </div>
+      {dialog.status === 'generating' ? (
+        <PlatformStatusMessage
+          tone="info"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="status"
+        >
+          生成中
+        </PlatformStatusMessage>
+      ) : null}
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+      </form>
+      {isGenerationReferenceMenuOpen && generationReferenceButtonRef
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu"
+              label="参考图来源"
+              placement="top-start"
+              style={buildPortalMenuStyle(
+                generationReferenceButtonRef.current,
+                'above',
+              )}
+            >
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen?.(false);
+                  setIsPickingGenerationReferenceFromCanvas?.(true);
+                }}
+              >
+                从画布中选择
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen?.(false);
+                  setIsPickingGenerationReferenceFromCanvas?.(false);
+                  onRequestUpload('generation-reference');
+                }}
+              >
+                上传图片
+              </PlatformFloatingMenuItem>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx b/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx
new file mode 100644
index 000000000..3e714d965
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx
@@ -0,0 +1,211 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { createRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ImageCanvasBottomToolbarView } from './ImageCanvasBottomToolbarView';
+
+describe('ImageCanvasBottomToolbarView', () => {
+  it('renders the canvas tools and forwards tool changes', () => {
+    const switchTool = vi.fn();
+    const specToolWrapRef = createRef<HTMLSpanElement>();
+    const musicToolWrapRef = createRef<HTMLSpanElement>();
+    const publicationToolWrapRef = createRef<HTMLSpanElement>();
+    render(
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool="generate"
+        onSwitchTool={switchTool}
+        onOpenToolOptions={vi.fn()}
+        onCloseToolOptions={vi.fn()}
+      />,
+    );
+
+    const toolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+
+    expect(
+      within(toolbar)
+        .getByRole('button', { name: '生成图片' })
+        .getAttribute('aria-pressed'),
+    ).toBe('false');
+    expect(
+      within(toolbar)
+        .getByRole('button', { name: '选择工具' })
+        .getAttribute('aria-pressed'),
+    ).toBe('false');
+
+    fireEvent.click(within(toolbar).getByRole('button', { name: '抓手工具' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '生成视频' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '生成规范' }));
+    fireEvent.click(
+      within(toolbar).getByRole('button', { name: '生成UI设计图' }),
+    );
+    fireEvent.click(within(toolbar).getByRole('button', { name: '生成音乐' }));
+    fireEvent.click(
+      within(toolbar).getByRole('button', { name: '生成图标素材' }),
+    );
+    fireEvent.click(within(toolbar).getByRole('button', { name: '宣发素材' }));
+
+    expect(switchTool).toHaveBeenNthCalledWith(1, 'hand');
+    expect(switchTool).toHaveBeenNthCalledWith(2, 'video');
+    expect(switchTool).toHaveBeenNthCalledWith(3, 'spec');
+    expect(switchTool).toHaveBeenNthCalledWith(4, 'ui-design');
+    expect(switchTool).toHaveBeenNthCalledWith(5, 'music');
+    expect(switchTool).toHaveBeenNthCalledWith(6, 'icon');
+    expect(switchTool).toHaveBeenNthCalledWith(7, 'publication');
+  });
+
+  it('only keeps the select and hand tools visibly pressed', () => {
+    const specToolWrapRef = createRef<HTMLSpanElement>();
+    const musicToolWrapRef = createRef<HTMLSpanElement>();
+    const publicationToolWrapRef = createRef<HTMLSpanElement>();
+    const renderToolbar = (effectiveTool: Parameters<
+      typeof ImageCanvasBottomToolbarView
+    >[0]['effectiveTool']) => (
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool={effectiveTool}
+        onSwitchTool={vi.fn()}
+        onOpenToolOptions={vi.fn()}
+        onCloseToolOptions={vi.fn()}
+      />
+    );
+
+    const { rerender } = render(renderToolbar('select'));
+    const toolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+
+    expect(
+      within(toolbar)
+        .getByRole('button', { name: '选择工具' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+
+    rerender(renderToolbar('hand'));
+
+    expect(
+      within(toolbar)
+        .getByRole('button', { name: '抓手工具' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+
+    for (const tool of [
+      ['upload', '上传工具'],
+      ['generate', '生成图片'],
+      ['video', '生成视频'],
+      ['music', '生成音乐'],
+      ['spec', '生成规范'],
+      ['character', '生成角色形象'],
+      ['icon', '生成图标素材'],
+      ['ui-design', '生成UI设计图'],
+      ['publication', '宣发素材'],
+    ] as const) {
+      rerender(renderToolbar(tool[0]));
+
+      expect(
+        within(toolbar)
+          .getByRole('button', { name: tool[1] })
+          .getAttribute('aria-pressed'),
+      ).toBe('false');
+    }
+  });
+
+  it('把宣发素材入口放在生成UI设计图右侧', () => {
+    const specToolWrapRef = createRef<HTMLSpanElement>();
+    const musicToolWrapRef = createRef<HTMLSpanElement>();
+    const publicationToolWrapRef = createRef<HTMLSpanElement>();
+    render(
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool="select"
+        onSwitchTool={vi.fn()}
+        onOpenToolOptions={vi.fn()}
+        onCloseToolOptions={vi.fn()}
+      />,
+    );
+
+    const toolNames = within(
+      screen.getByRole('toolbar', { name: 'AI画布工具栏' }),
+    )
+      .getAllByRole('button')
+      .map((button) => button.getAttribute('aria-label'));
+
+    expect(toolNames).toEqual([
+      '选择工具',
+      '抓手工具',
+      '上传工具',
+      '生成图片',
+      '生成视频',
+      '生成音乐',
+      '生成规范',
+      '生成角色形象',
+      '生成图标素材',
+      '生成UI设计图',
+      '宣发素材',
+    ]);
+  });
+
+  it('uses an upload-specific icon for the upload tool', () => {
+    const specToolWrapRef = createRef<HTMLSpanElement>();
+    const musicToolWrapRef = createRef<HTMLSpanElement>();
+    const publicationToolWrapRef = createRef<HTMLSpanElement>();
+    render(
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool="select"
+        onSwitchTool={vi.fn()}
+        onOpenToolOptions={vi.fn()}
+        onCloseToolOptions={vi.fn()}
+      />,
+    );
+
+    expect(
+      within(
+        screen.getByRole('toolbar', { name: 'AI画布工具栏' }),
+      )
+        .getByRole('button', { name: '上传工具' })
+        .querySelector('.lucide-upload'),
+    ).toBeTruthy();
+  });
+
+  it('opens and closes bottom option tools on hover', () => {
+    const openToolOptions = vi.fn();
+    const closeToolOptions = vi.fn();
+    const specToolWrapRef = createRef<HTMLSpanElement>();
+    const musicToolWrapRef = createRef<HTMLSpanElement>();
+    const publicationToolWrapRef = createRef<HTMLSpanElement>();
+    render(
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool="select"
+        onSwitchTool={vi.fn()}
+        onOpenToolOptions={openToolOptions}
+        onCloseToolOptions={closeToolOptions}
+      />,
+    );
+
+    fireEvent.pointerEnter(specToolWrapRef.current!);
+    fireEvent.pointerLeave(specToolWrapRef.current!);
+    fireEvent.pointerEnter(musicToolWrapRef.current!);
+    fireEvent.pointerLeave(musicToolWrapRef.current!);
+    fireEvent.pointerEnter(publicationToolWrapRef.current!);
+    fireEvent.pointerLeave(publicationToolWrapRef.current!);
+
+    expect(openToolOptions).toHaveBeenNthCalledWith(1, 'spec');
+    expect(closeToolOptions).toHaveBeenNthCalledWith(1, 'spec');
+    expect(openToolOptions).toHaveBeenNthCalledWith(2, 'music');
+    expect(closeToolOptions).toHaveBeenNthCalledWith(2, 'music');
+    expect(openToolOptions).toHaveBeenNthCalledWith(3, 'publication');
+    expect(closeToolOptions).toHaveBeenNthCalledWith(3, 'publication');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasBottomToolbarView.tsx b/src/components/image-editor/ImageCanvasBottomToolbarView.tsx
new file mode 100644
index 000000000..ae198470b
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasBottomToolbarView.tsx
@@ -0,0 +1,148 @@
+import {
+  AppWindow,
+  Clapperboard,
+  ClipboardList,
+  Grid2X2,
+  Hand,
+  ImageIcon,
+  Megaphone,
+  MousePointer2,
+  Music,
+  Upload,
+  UserRound,
+} from 'lucide-react';
+import type { RefObject } from 'react';
+
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type { CanvasTool } from './ImageCanvasEditorTypes';
+
+type ToolbarOptionTool = Extract<CanvasTool, 'music' | 'spec' | 'publication'>;
+
+type ImageCanvasBottomToolbarViewProps = {
+  specToolWrapRef: RefObject<HTMLSpanElement | null>;
+  musicToolWrapRef: RefObject<HTMLSpanElement | null>;
+  publicationToolWrapRef: RefObject<HTMLSpanElement | null>;
+  effectiveTool: CanvasTool;
+  onSwitchTool: (tool: CanvasTool) => void;
+  onOpenToolOptions: (tool: ToolbarOptionTool) => void;
+  onCloseToolOptions: (tool: ToolbarOptionTool) => void;
+};
+
+const canvasTools: Array<{
+  id: CanvasTool;
+  label: string;
+  icon: typeof MousePointer2;
+  separatorBefore?: boolean;
+}> = [
+  { id: 'select', label: '选择工具', icon: MousePointer2 },
+  { id: 'hand', label: '抓手工具', icon: Hand },
+  { id: 'upload', label: '上传工具', icon: Upload },
+  {
+    id: 'generate',
+    label: '生成图片',
+    icon: ImageIcon,
+    separatorBefore: true,
+  },
+  { id: 'video', label: '生成视频', icon: Clapperboard },
+  { id: 'music', label: '生成音乐', icon: Music },
+  {
+    id: 'spec',
+    label: '生成规范',
+    icon: ClipboardList,
+    separatorBefore: true,
+  },
+  { id: 'character', label: '生成角色形象', icon: UserRound },
+  { id: 'icon', label: '生成图标素材', icon: Grid2X2 },
+  { id: 'ui-design', label: '生成UI设计图', icon: AppWindow },
+  { id: 'publication', label: '宣发素材', icon: Megaphone },
+];
+
+function isToolbarOptionTool(tool: CanvasTool): tool is ToolbarOptionTool {
+  return tool === 'music' || tool === 'spec' || tool === 'publication';
+}
+
+function hasPersistentPressedState(tool: CanvasTool) {
+  return tool === 'select' || tool === 'hand';
+}
+
+export function ImageCanvasBottomToolbarView({
+  specToolWrapRef,
+  musicToolWrapRef,
+  publicationToolWrapRef,
+  effectiveTool,
+  onSwitchTool,
+  onOpenToolOptions,
+  onCloseToolOptions,
+}: ImageCanvasBottomToolbarViewProps) {
+  return (
+    <div
+      className="image-canvas-editor__bottom-toolbar"
+      role="toolbar"
+      aria-label="AI画布工具栏"
+      onPointerDown={(event) => event.stopPropagation()}
+    >
+      {canvasTools.map(({ id, label, icon: Icon, separatorBefore }) => {
+        if (isToolbarOptionTool(id)) {
+          return (
+            <span key={id} className="image-canvas-editor__bottom-tool-group">
+              {separatorBefore ? (
+                <span
+                  aria-hidden="true"
+                  className="image-canvas-editor__bottom-toolbar-divider"
+                />
+              ) : null}
+              <span
+                ref={
+                  id === 'spec'
+                    ? specToolWrapRef
+                    : id === 'music'
+                      ? musicToolWrapRef
+                      : publicationToolWrapRef
+                }
+                className={[
+                  'image-canvas-editor__bottom-toolbar-option-wrap',
+                  id === 'spec' ? 'image-canvas-editor__spec-tool-wrap' : '',
+                  id === 'publication'
+                    ? 'image-canvas-editor__publication-tool-wrap'
+                    : '',
+                ]
+                  .filter(Boolean)
+                  .join(' ')}
+                onPointerEnter={() => onOpenToolOptions(id)}
+                onPointerLeave={() => onCloseToolOptions(id)}
+                onFocus={() => onOpenToolOptions(id)}
+                onBlur={() => onCloseToolOptions(id)}
+              >
+                <EditorIconButton
+                  label={label}
+                  title={label}
+                  icon={Icon}
+                  pressed={hasPersistentPressedState(id) && effectiveTool === id}
+                  onClick={() => onSwitchTool(id)}
+                />
+              </span>
+            </span>
+          );
+        }
+
+        return (
+          <span key={id} className="image-canvas-editor__bottom-tool-group">
+            {separatorBefore ? (
+              <span
+                aria-hidden="true"
+                className="image-canvas-editor__bottom-toolbar-divider"
+              />
+            ) : null}
+            <EditorIconButton
+              label={label}
+              title={label}
+              icon={Icon}
+              pressed={hasPersistentPressedState(id) && effectiveTool === id}
+              onClick={() => onSwitchTool(id)}
+            />
+          </span>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx
new file mode 100644
index 000000000..deca396d4
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.test.tsx
@@ -0,0 +1,250 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer, CharacterAnimationPanelState } from './ImageCanvasEditorTypes';
+import { ImageCanvasCharacterAnimationPanelView } from './ImageCanvasCharacterAnimationPanelView';
+
+
+function createSourceLayer(): CanvasLayer {
+  return {
+    id: 'layer-a',
+    resourceId: 'resource-a',
+    title: '角色源图',
+    src: 'data:image/png;base64,Y2hhcmFjdGVy',
+    x: 0,
+    y: 0,
+    width: 128,
+    height: 128,
+    originalWidth: 128,
+    originalHeight: 128,
+    zIndex: 1,
+    sourceType: 'uploaded',
+  };
+}
+
+function createPanel(
+  patch: Partial<CharacterAnimationPanelState> = {},
+): CharacterAnimationPanelState {
+  return {
+    sourceLayerId: 'layer-a',
+    promptText: '待机动作',
+    resolution: '480p',
+    ratio: 'same',
+    frameCount: 32,
+    durationSeconds: 4,
+    status: 'idle',
+    ...patch,
+  };
+}
+
+function CharacterAnimationPanelHarness({
+  initialPanel,
+  onSubmit = vi.fn(),
+  onUpdateDuration,
+}: {
+  initialPanel: CharacterAnimationPanelState;
+  onSubmit?: () => void;
+  onUpdateDuration?: (frameCountValue: string) => void;
+}) {
+  const [panel, setPanel] = useState<CharacterAnimationPanelState | null>(
+    initialPanel,
+  );
+
+  const updateDuration =
+    onUpdateDuration ??
+    ((frameCountValue: string) => {
+      const frameCount = Number(frameCountValue);
+      setPanel((currentPanel) =>
+        currentPanel
+          ? {
+              ...currentPanel,
+              frameCount:
+                frameCount === 48 ? 48 : frameCount === 40 ? 40 : 32,
+              durationSeconds:
+                frameCount === 48 ? 6 : frameCount === 40 ? 5 : 4,
+              status:
+                currentPanel.status === 'failed'
+                  ? 'idle'
+                  : currentPanel.status,
+              errorMessage:
+                currentPanel.status === 'failed'
+                  ? undefined
+                  : currentPanel.errorMessage,
+            }
+          : currentPanel,
+      );
+    });
+
+  return panel ? (
+    <div>
+      <ImageCanvasCharacterAnimationPanelView
+        panel={panel}
+        sourceLayer={createSourceLayer()}
+        style={{ left: 12, top: 24 }}
+        price={18}
+        setCharacterAnimationPanel={setPanel}
+        onUpdateDuration={updateDuration}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="当前动画描述">{panel.promptText}</output>
+      <output aria-label="当前分辨率">{panel.resolution}</output>
+      <output aria-label="当前比例">{panel.ratio}</output>
+      <output aria-label="当前帧数">{panel.frameCount}</output>
+      <output aria-label="当前时长">{panel.durationSeconds}</output>
+      <output aria-label="当前状态">{panel.status}</output>
+      <output aria-label="当前错误">{panel.errorMessage ?? '-'}</output>
+    </div>
+  ) : (
+    <output aria-label="面板状态">closed</output>
+  );
+}
+
+describe('ImageCanvasCharacterAnimationPanelView', () => {
+  it('keeps source reference first and updates prompt, resolution and ratio from a menu while clearing failed state', () => {
+    render(
+      <CharacterAnimationPanelHarness
+        initialPanel={createPanel({
+          status: 'failed',
+          errorMessage: '旧错误',
+        })}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('动画描述'), {
+      target: { value: `${'a'.repeat(4001)}` },
+    });
+    fireEvent.click(
+      screen.getByRole('button', { name: '动画参数 同图尺寸 · 4秒 · 480p' }),
+    );
+    const menu = screen.getByRole('menu', { name: '动画参数选项' });
+    fireEvent.click(screen.getByRole('button', { name: '清晰度 720p' }));
+    fireEvent.click(screen.getByRole('button', { name: '比例 16:9' }));
+
+    expect(screen.getByRole('menu', { name: '动画参数选项' })).toBeTruthy();
+    expect(screen.getByLabelText('当前动画描述').textContent).toHaveLength(4000);
+    expect(screen.getByLabelText('当前分辨率').textContent).toBe('720p');
+    expect(screen.getByLabelText('当前比例').textContent).toBe('16:9');
+    expect(menu).toBeTruthy();
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+  });
+
+  it('clicks the parent animation panel to collapse the parameter menu', () => {
+    render(
+      <CharacterAnimationPanelHarness initialPanel={createPanel()} />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '动画参数 同图尺寸 · 4秒 · 480p' }),
+    );
+    expect(screen.getByRole('menu', { name: '动画参数选项' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('textbox', { name: '动画描述' }));
+
+    expect(screen.queryByRole('menu', { name: '动画参数选项' })).toBeNull();
+  });
+
+  it('applies preset prompt and duration updates', () => {
+    const updateDuration = vi.fn();
+    render(
+      <CharacterAnimationPanelHarness
+        initialPanel={createPanel({
+          status: 'failed',
+          errorMessage: '旧错误',
+        })}
+        onUpdateDuration={updateDuration}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '行走' }));
+    fireEvent.click(
+      screen.getByRole('button', { name: '动画参数 同图尺寸 · 4秒 · 480p' }),
+    );
+    fireEvent.click(screen.getByRole('button', { name: '时长 48帧·6秒' }));
+
+    expect(screen.getByLabelText('当前动画描述').textContent).toBe(
+      '循环行走动作，步伐稳定。',
+    );
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+    expect(updateDuration).toHaveBeenCalledWith('48');
+  });
+
+  it('submits only when idle and closes through its interface', () => {
+    const submitCharacterAnimation = vi.fn();
+    render(
+      <CharacterAnimationPanelHarness
+        initialPanel={createPanel()}
+        onSubmit={submitCharacterAnimation}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成18泥点' }));
+    fireEvent.click(
+      screen.getByRole('button', { name: '关闭角色动画生成面板' }),
+    );
+
+    expect(submitCharacterAnimation).toHaveBeenCalledTimes(1);
+    expect(screen.getByLabelText('面板状态').textContent).toBe('closed');
+  });
+
+  it('keeps generating panels disabled and does not submit', () => {
+    const submitCharacterAnimation = vi.fn();
+    render(
+      <CharacterAnimationPanelHarness
+        initialPanel={createPanel({ status: 'generating' })}
+        onSubmit={submitCharacterAnimation}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成中' }));
+
+    expect((screen.getByLabelText('动画描述') as HTMLTextAreaElement).disabled).toBe(
+      true,
+    );
+    expect((screen.getByRole('button', { name: '待机' }) as HTMLButtonElement).disabled).toBe(
+      true,
+    );
+    expect(submitCharacterAnimation).not.toHaveBeenCalled();
+  });
+
+  it('renders completed frame count and failed error state', () => {
+    const result = {
+      taskId: 'task-a',
+      model: 'seedance2.0-fast' as const,
+      prompt: '行走动作',
+      previewVideoPath: '/preview.mp4',
+      frames: [],
+      frameCount: 40,
+      durationSeconds: 5,
+      fps: 8,
+      priceMudPoints: 18,
+    };
+
+    const { rerender } = render(
+      <CharacterAnimationPanelHarness
+        initialPanel={createPanel({
+          status: 'completed',
+          result,
+        })}
+      />,
+    );
+
+    expect(screen.getByText('已生成 40 帧')).toBeTruthy();
+
+    rerender(
+      <CharacterAnimationPanelHarness
+        key="failed"
+        initialPanel={createPanel({
+          status: 'failed',
+          errorMessage: '生成失败',
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('alert').textContent).toContain('生成失败');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.tsx b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.tsx
new file mode 100644
index 000000000..0414a17fb
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCharacterAnimationPanelView.tsx
@@ -0,0 +1,370 @@
+import { ChevronDown, X } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import type {
+  EditorCharacterAnimationRatio,
+  EditorCharacterAnimationResolution,
+} from '../../services/image-editor/editorProjectClient';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformFloatingMenu } from '../common/PlatformFloatingMenu';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type {
+  CanvasLayer,
+  CharacterAnimationPanelState,
+} from './ImageCanvasEditorTypes';
+import {
+  CHARACTER_ANIMATION_ACTION_PROMPTS,
+  CHARACTER_ANIMATION_DURATION_OPTIONS,
+  CHARACTER_ANIMATION_RATIO_OPTIONS,
+} from './ImageCanvasGenerationModel';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasCharacterAnimationPanelViewProps = {
+  panel: CharacterAnimationPanelState;
+  sourceLayer: CanvasLayer;
+  style: CSSProperties;
+  price: number;
+  setCharacterAnimationPanel: Dispatch<
+    SetStateAction<CharacterAnimationPanelState | null>
+  >;
+  onUpdateDuration: (frameCountValue: string) => void;
+  onSubmit: () => void;
+};
+
+function resetFailedPanelStatus<T extends { status: string; errorMessage?: string }>(
+  panel: T,
+) {
+  return {
+    ...panel,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+  };
+}
+
+function buildLocalMenuStyle(anchor: HTMLElement | null): CSSProperties {
+  const rect = anchor?.getBoundingClientRect();
+  if (!rect) {
+    return {
+      position: 'fixed',
+      left: 0,
+      top: 0,
+      right: 'auto',
+      bottom: 'auto',
+      zIndex: 70,
+    };
+  }
+
+  return {
+    position: 'fixed',
+    left: Math.round(rect.left),
+    top: Math.round(rect.top),
+    right: 'auto',
+    bottom: 'auto',
+    zIndex: 70,
+    transform: 'translateY(calc(-100% - 0.45rem))',
+  };
+}
+
+function renderPanelPortal(node: ReactNode) {
+  if (typeof document === 'undefined') {
+    return node;
+  }
+  // 中文注释：参数菜单挂到页面级，避免被角色动画面板滚动边界裁切。
+  return document.body ? createPortal(node, document.body) : node;
+}
+
+function getRatioLabel(value: EditorCharacterAnimationRatio) {
+  return value === 'same' ? '同图尺寸' : value;
+}
+
+function AnimationOptionChoice({
+  children,
+  selected,
+  className,
+  ariaLabel,
+  disabled,
+  onClick,
+}: {
+  children: ReactNode;
+  selected: boolean;
+  className?: string;
+  ariaLabel?: string;
+  disabled?: boolean;
+  onClick?: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className={['image-canvas-editor__option-popover-choice', className]
+        .filter(Boolean)
+        .join(' ')}
+      aria-label={ariaLabel}
+      aria-pressed={selected}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function ImageCanvasCharacterAnimationPanelView({
+  panel,
+  sourceLayer,
+  style,
+  price,
+  setCharacterAnimationPanel,
+  onUpdateDuration,
+  onSubmit,
+}: ImageCanvasCharacterAnimationPanelViewProps) {
+  const [isParameterMenuOpen, setIsParameterMenuOpen] = useState(false);
+  const parameterButtonRef = useRef<HTMLButtonElement | null>(null);
+  const isGenerating = panel.status === 'generating';
+  const ratioLabel = getRatioLabel(panel.ratio);
+  const dismissParameterMenu = useCallback(() => {
+    setIsParameterMenuOpen(false);
+  }, []);
+
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isParameterMenuOpen,
+    boundaryRefs: [parameterButtonRef],
+    onDismiss: dismissParameterMenu,
+  });
+
+  const updatePanel = (patch: Partial<CharacterAnimationPanelState>) => {
+    setCharacterAnimationPanel((currentPanel) =>
+      currentPanel
+        ? {
+            ...resetFailedPanelStatus(currentPanel),
+            ...patch,
+          }
+        : currentPanel,
+    );
+  };
+  const closePanel = () => {
+    setCharacterAnimationPanel((currentPanel) =>
+      currentPanel && isGenerating
+        ? currentPanel
+        : null,
+    );
+  };
+
+  return (
+    <>
+      <form
+        className="image-canvas-editor__character-animation-panel image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image image-canvas-editor__generation-composer--character-animation"
+        style={style}
+        role="dialog"
+        aria-label="角色动画生成面板"
+        onPointerDown={(event) => event.stopPropagation()}
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (!isGenerating) {
+            onSubmit();
+          }
+        }}
+      >
+        <div className="image-canvas-editor__reference-strip">
+          <span
+            className="image-canvas-editor__reference-chip image-canvas-editor__reference-chip--character"
+            title={sourceLayer.title}
+          >
+            <span className="image-canvas-editor__reference-chip-icon">
+              <img src={sourceLayer.src} alt="" aria-hidden="true" />
+            </span>
+            <span className="image-canvas-editor__reference-chip-label">
+              {sourceLayer.title}
+            </span>
+          </span>
+        </div>
+        <EditorIconButton
+          className="image-canvas-editor__generation-close"
+          label="关闭角色动画生成面板"
+          title="关闭"
+          icon={X}
+          variant="surfaceFloating"
+          disabled={isGenerating}
+          onClick={closePanel}
+        />
+        <PlatformTextField
+          variant="textarea"
+          aria-label="动画描述"
+          value={panel.promptText}
+          maxLength={4000}
+          disabled={isGenerating}
+          placeholder="你希望角色做什么动作？"
+          size="sm"
+          density="compact"
+          className="image-canvas-editor__generation-prompt image-canvas-editor__generation-prompt--borderless image-canvas-editor__character-animation-textarea"
+          onChange={(event) =>
+            updatePanel({ promptText: event.target.value.slice(0, 4000) })
+          }
+        />
+        <div className="image-canvas-editor__character-animation-presets">
+          {CHARACTER_ANIMATION_ACTION_PROMPTS.map((preset) => (
+            <button
+              key={preset.label}
+              type="button"
+              className="image-canvas-editor__character-animation-preset"
+              disabled={isGenerating}
+              onClick={() =>
+                setCharacterAnimationPanel((currentPanel) =>
+                  currentPanel
+                    ? {
+                        ...currentPanel,
+                        promptText: preset.text,
+                        status: 'idle',
+                        errorMessage: undefined,
+                      }
+                    : currentPanel,
+                )
+              }
+            >
+              {preset.label}
+            </button>
+          ))}
+        </div>
+        <div className="image-canvas-editor__character-animation-footer">
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions">
+            <PlatformInlineOptionButton
+              ref={parameterButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+              aria-label={`动画参数 ${ratioLabel} · ${panel.durationSeconds}秒 · ${panel.resolution}`}
+              aria-expanded={isParameterMenuOpen}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() => setIsParameterMenuOpen((open) => !open)}
+            >
+              {ratioLabel} · {panel.durationSeconds}秒 · {panel.resolution}
+            </PlatformInlineOptionButton>
+          </div>
+          <PlatformActionButton
+            type="submit"
+            tone="secondary"
+            size="xs"
+            shape="pill"
+            className="image-canvas-editor__character-animation-submit"
+            disabled={isGenerating}
+          >
+            {isGenerating ? '生成中' : `生成${price}泥点`}
+          </PlatformActionButton>
+        </div>
+        <span
+          className="image-canvas-editor__character-animation-summary-text"
+          title={panel.promptText.trim() || undefined}
+          aria-label={`生成文本：${panel.promptText.trim() || '动画描述'}`}
+        >
+          {panel.promptText.trim() ? panel.promptText.trim() : '动画描述'}
+        </span>
+        {panel.status === 'completed' && panel.result ? (
+          <PlatformStatusMessage
+            tone="success"
+            surface="platform"
+            size="xs"
+            role="status"
+          >
+            已生成 {panel.result.frameCount} 帧
+          </PlatformStatusMessage>
+        ) : null}
+        {panel.status === 'failed' ? (
+          <PlatformStatusMessage
+            tone="error"
+            surface="platform"
+            size="xs"
+            role="alert"
+          >
+            {panel.errorMessage}
+          </PlatformStatusMessage>
+        ) : null}
+      </form>
+      {isParameterMenuOpen
+        ? renderPanelPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__option-popover image-canvas-editor__portal-menu"
+              label="动画参数选项"
+              placement="top-start"
+              style={buildLocalMenuStyle(parameterButtonRef.current)}
+              onPointerDown={(event) => event.stopPropagation()}
+            >
+              <div className="image-canvas-editor__option-popover-sections">
+                <section className="image-canvas-editor__option-popover-section">
+                  <span className="image-canvas-editor__option-popover-title">
+                    比例
+                  </span>
+                  <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--card">
+                    {CHARACTER_ANIMATION_RATIO_OPTIONS.map((option) => (
+                      <AnimationOptionChoice
+                        key={option.value}
+                        selected={panel.ratio === option.value}
+                        disabled={isGenerating}
+                        className="image-canvas-editor__option-popover-choice--ratio"
+                        ariaLabel={`比例 ${getRatioLabel(option.value)}`}
+                        onClick={() => updatePanel({ ratio: option.value })}
+                      >
+                        <span
+                          className="image-canvas-editor__ratio-wireframe"
+                          data-ratio={option.value}
+                          aria-hidden="true"
+                        />
+                        <span>{getRatioLabel(option.value)}</span>
+                      </AnimationOptionChoice>
+                    ))}
+                  </div>
+                </section>
+                <section className="image-canvas-editor__option-popover-section">
+                  <span className="image-canvas-editor__option-popover-title">
+                    时长
+                  </span>
+                  <div className="image-canvas-editor__option-popover-items">
+                    {CHARACTER_ANIMATION_DURATION_OPTIONS.map((option) => (
+                      <AnimationOptionChoice
+                        key={option.frameCount}
+                        selected={panel.frameCount === option.frameCount}
+                        disabled={isGenerating}
+                        ariaLabel={`时长 ${option.label}`}
+                        onClick={() => onUpdateDuration(String(option.frameCount))}
+                      >
+                        {option.label}
+                      </AnimationOptionChoice>
+                    ))}
+                  </div>
+                </section>
+                <section className="image-canvas-editor__option-popover-section">
+                  <span className="image-canvas-editor__option-popover-title">
+                    清晰度
+                  </span>
+                  <div className="image-canvas-editor__option-popover-items">
+                    {(['480p', '720p'] as EditorCharacterAnimationResolution[]).map(
+                      (resolution) => (
+                        <AnimationOptionChoice
+                          key={resolution}
+                          selected={panel.resolution === resolution}
+                          disabled={isGenerating}
+                          ariaLabel={`清晰度 ${resolution}`}
+                          onClick={() => updatePanel({ resolution })}
+                        >
+                          {resolution}
+                        </AnimationOptionChoice>
+                      ),
+                    )}
+                  </div>
+                </section>
+              </div>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx
new file mode 100644
index 000000000..b2c162ad8
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.test.tsx
@@ -0,0 +1,225 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { createRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  GenerateDialogState,
+  SpecGenerationType,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasCharacterGenerationComposerView } from './ImageCanvasCharacterGenerationComposerView';
+import { IMAGE_MODEL_GPT_IMAGE_2 } from './ImageCanvasGenerationModel';
+
+function createDialog(
+  patch: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'character',
+    prompt: '旧角色设定',
+    status: 'idle',
+    characterSpecReference: {
+      id: 'spec-a',
+      label: '角色规范A',
+      src: 'data:image/png;base64,c3BlYw==',
+    },
+    characterReferences: [
+      {
+        id: 'ref-a',
+        label: '参考图A',
+        src: 'data:image/png;base64,cmVm',
+      },
+    ],
+    ...patch,
+  };
+}
+
+function CharacterGenerationHarness({
+  initialDialog = createDialog(),
+  onOpenSpecDialog = vi.fn(),
+  onRequestUpload = vi.fn(),
+  onSubmit = vi.fn(),
+  onRememberImageModel = vi.fn(),
+}: {
+  initialDialog?: GenerateDialogState;
+  onOpenSpecDialog?: (specType: SpecGenerationType) => void;
+  onRequestUpload?: (target: UploadTarget) => void;
+  onSubmit?: (dialog: GenerateDialogState) => void;
+  onRememberImageModel?: (model: string) => void;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+  const [isCharacterSpecMenuOpen, setIsCharacterSpecMenuOpen] =
+    useState(false);
+  const [
+    isCharacterReferenceMenuOpen,
+    setIsCharacterReferenceMenuOpen,
+  ] = useState(false);
+  const [isPickingSpec, setIsPickingSpec] = useState(false);
+  const [isPickingReference, setIsPickingReference] = useState(false);
+  const characterSpecButtonRef = createRef<HTMLButtonElement>();
+  const characterReferenceButtonRef = createRef<HTMLButtonElement>();
+
+  return dialog ? (
+    <div>
+      <ImageCanvasCharacterGenerationComposerView
+        dialog={dialog}
+        style={{ left: 10, top: 20 }}
+        characterSpecButtonRef={characterSpecButtonRef}
+        characterReferenceButtonRef={characterReferenceButtonRef}
+        isCharacterSpecMenuOpen={isCharacterSpecMenuOpen}
+        isCharacterReferenceMenuOpen={isCharacterReferenceMenuOpen}
+        setGenerateDialog={setDialog}
+        setIsCharacterSpecMenuOpen={setIsCharacterSpecMenuOpen}
+        setIsCharacterReferenceMenuOpen={setIsCharacterReferenceMenuOpen}
+        setIsPickingCharacterSpecFromCanvas={setIsPickingSpec}
+        setIsPickingCharacterReferenceFromCanvas={setIsPickingReference}
+        renderEditorPortal={(node) => node}
+        buildPortalMenuStyle={() => ({ position: 'fixed', left: 0, top: 0 })}
+        onOpenSpecDialog={onOpenSpecDialog}
+        onRequestUpload={onRequestUpload}
+        onRememberImageModel={onRememberImageModel}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="当前角色设定">{dialog.prompt}</output>
+      <output aria-label="当前状态">{dialog.status}</output>
+      <output aria-label="当前错误">{dialog.errorMessage ?? '-'}</output>
+      <output aria-label="选择角色规范">{String(isPickingSpec)}</output>
+      <output aria-label="选择常规参考图">{String(isPickingReference)}</output>
+    </div>
+  ) : null;
+}
+
+describe('ImageCanvasCharacterGenerationComposerView', () => {
+  it('keeps the prompt as a borderless single text input with a question placeholder', () => {
+    render(<CharacterGenerationHarness />);
+
+    const panel = screen.getByRole('dialog', { name: '生成角色形象' });
+    const prompt = screen.getByRole('textbox', { name: '角色设定' });
+
+    expect(
+      Array.from(panel.querySelectorAll('.image-canvas-editor__field-title'))
+        .map((node) => node.textContent)
+        .join(''),
+    ).not.toContain('角色设定');
+    expect(prompt.getAttribute('placeholder')).toBe('你希望角色如何设计？');
+    expect(prompt.className).toContain(
+      'image-canvas-editor__generation-prompt--borderless',
+    );
+  });
+
+  it('updates character prompt, clears failed state and submits', () => {
+    const submitCharacter = vi.fn();
+    render(
+      <CharacterGenerationHarness
+        initialDialog={createDialog({
+          status: 'failed',
+          errorMessage: '角色失败',
+        })}
+        onSubmit={submitCharacter}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('角色设定'), {
+      target: { value: '新的角色设定' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect(screen.getByLabelText('当前角色设定').textContent).toBe(
+      '新的角色设定',
+    );
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+    expect(submitCharacter).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: '新的角色设定', status: 'idle' }),
+    );
+  });
+
+  it('updates the submit price when switching the character image model', () => {
+    const rememberImageModel = vi.fn();
+    render(
+      <CharacterGenerationHarness
+        initialDialog={createDialog({
+          imageModel: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+        })}
+        onRememberImageModel={rememberImageModel}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: '生成' }).textContent).toBe(
+      '生成12泥点',
+    );
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片模型 nanobanana2' }),
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'gpt-image-2' }));
+
+    expect(rememberImageModel).toHaveBeenCalledWith(IMAGE_MODEL_GPT_IMAGE_2);
+    expect(screen.getByRole('button', { name: '生成' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('routes character reference menus to canvas picking, spec creation and upload', () => {
+    const openSpecDialog = vi.fn();
+    const requestUpload = vi.fn();
+    render(
+      <CharacterGenerationHarness
+        onOpenSpecDialog={openSpecDialog}
+        onRequestUpload={requestUpload}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '角色规范A' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+
+    expect(screen.getByLabelText('选择角色规范').textContent).toBe('true');
+
+    fireEvent.click(screen.getByRole('button', { name: '角色规范A' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '新建角色规范' }));
+
+    expect(openSpecDialog).toHaveBeenCalledWith('character');
+
+    fireEvent.click(screen.getByRole('button', { name: '角色规范A' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+
+    expect(requestUpload).toHaveBeenCalledWith('character-spec');
+
+    fireEvent.click(screen.getByRole('button', { name: '上传常规参考图' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+
+    expect(screen.getByLabelText('选择常规参考图').textContent).toBe('true');
+  });
+
+  it('removes bound character spec and regular references from their delete buttons', () => {
+    render(<CharacterGenerationHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '删除角色规范' }));
+    expect(screen.getByRole('button', { name: '角色规范' })).toBeTruthy();
+    expect(screen.queryByRole('button', { name: '角色规范A' })).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '删除参考图A' }));
+    expect(screen.queryByText('参考图A')).toBeNull();
+  });
+
+  it('clicks the parent character panel to collapse reference menus', () => {
+    render(
+      <CharacterGenerationHarness
+        initialDialog={createDialog()}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '角色规范A' }));
+    expect(screen.getByRole('menu', { name: '角色规范来源' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('textbox', { name: '角色设定' }));
+
+    expect(
+      screen.queryByRole('menu', { name: '角色规范来源' }),
+    ).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx
new file mode 100644
index 000000000..b132d6a21
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCharacterGenerationComposerView.tsx
@@ -0,0 +1,306 @@
+import { ClipboardList, ImagePlus } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import type {
+  CharacterReferenceImage,
+  GenerateDialogState,
+  SpecGenerationType,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import { calculateEditorImageGenerationPrice } from './ImageCanvasGenerationModel';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasCharacterGenerationComposerViewProps = {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  characterSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  characterReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  isCharacterSpecMenuOpen: boolean;
+  isCharacterReferenceMenuOpen: boolean;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setIsCharacterSpecMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsCharacterReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPickingCharacterSpecFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingCharacterReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  renderEditorPortal: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onOpenSpecDialog: (specType: SpecGenerationType) => void;
+  onRequestUpload: (target: UploadTarget) => void;
+  onRememberImageModel: (model: string) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+
+function resetFailedDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function ReferenceChip({
+  reference,
+  index,
+  onRemove,
+}: {
+  reference: CharacterReferenceImage;
+  index: number;
+  onRemove: () => void;
+}) {
+  const label = reference.label || `参考图${index + 1}`;
+  return (
+    <ImageCanvasReferenceSlot
+      tone="character"
+      icon={<ImagePlus className="h-4 w-4" aria-hidden="true" />}
+      imageSrc={reference.src}
+      label={label}
+      ariaLabel={label}
+      title={reference.label}
+      onRemove={onRemove}
+      removeLabel={`删除${label}`}
+    />
+  );
+}
+
+export function ImageCanvasCharacterGenerationComposerView({
+  dialog,
+  style,
+  characterSpecButtonRef,
+  characterReferenceButtonRef,
+  isCharacterSpecMenuOpen,
+  isCharacterReferenceMenuOpen,
+  setGenerateDialog,
+  setIsCharacterSpecMenuOpen,
+  setIsCharacterReferenceMenuOpen,
+  setIsPickingCharacterSpecFromCanvas,
+  setIsPickingCharacterReferenceFromCanvas,
+  renderEditorPortal,
+  buildPortalMenuStyle,
+  onOpenSpecDialog,
+  onRequestUpload,
+  onRememberImageModel,
+  onSubmit,
+}: ImageCanvasCharacterGenerationComposerViewProps) {
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isCharacterSpecMenuOpen || isCharacterReferenceMenuOpen,
+    boundaryRefs: [characterSpecButtonRef, characterReferenceButtonRef],
+    onDismiss: () => {
+      setIsCharacterSpecMenuOpen(false);
+      setIsCharacterReferenceMenuOpen(false);
+    },
+  });
+
+  return (
+    <form
+      className="image-canvas-editor__character-composer"
+      style={style}
+      role="dialog"
+      aria-label="生成角色形象"
+      onPointerDown={(event) => event.stopPropagation()}
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (dialog.status !== 'generating') {
+          onSubmit(dialog);
+        }
+      }}
+    >
+      <div className="image-canvas-editor__reference-strip">
+        <ImageCanvasReferenceSlot
+          buttonRef={characterSpecButtonRef}
+          tone="spec"
+          icon={<ClipboardList className="h-4 w-4" aria-hidden="true" />}
+          imageSrc={dialog.characterSpecReference?.src}
+          label="角色规范"
+          ariaLabel={dialog.characterSpecReference?.label ?? '角色规范'}
+          title={dialog.characterSpecReference?.label ?? '角色规范'}
+          disabled={dialog.status === 'generating'}
+          isAdd={!dialog.characterSpecReference}
+          onClick={() => setIsCharacterSpecMenuOpen((open) => !open)}
+          onRemove={
+            dialog.characterSpecReference
+              ? () =>
+                  setGenerateDialog((currentDialog) =>
+                    currentDialog?.mode === 'character'
+                      ? {
+                          ...resetFailedDialogStatus(currentDialog),
+                          characterSpecReference: null,
+                        }
+                      : currentDialog,
+                  )
+              : undefined
+          }
+          removeLabel="删除角色规范"
+        />
+        {isCharacterSpecMenuOpen
+          ? renderEditorPortal(
+              <PlatformFloatingMenu
+                className="image-canvas-editor__character-spec-menu image-canvas-editor__portal-menu"
+                label="角色规范来源"
+                placement="top-start"
+                style={buildPortalMenuStyle(
+                  characterSpecButtonRef.current,
+                  'above',
+                )}
+              >
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsPickingCharacterSpecFromCanvas(true);
+                    setIsCharacterSpecMenuOpen(false);
+                  }}
+                >
+                  从画布中选择
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsCharacterSpecMenuOpen(false);
+                    onOpenSpecDialog('character');
+                  }}
+                >
+                  新建角色规范
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsCharacterSpecMenuOpen(false);
+                    onRequestUpload('character-spec');
+                  }}
+                >
+                  上传图片
+                </PlatformFloatingMenuItem>
+              </PlatformFloatingMenu>,
+            )
+          : null}
+        {(dialog.characterReferences ?? []).map((reference, index) => (
+          <ReferenceChip
+            key={reference.id}
+            reference={reference}
+            index={index}
+            onRemove={() =>
+              setGenerateDialog((currentDialog) =>
+                currentDialog?.mode === 'character'
+                  ? {
+                      ...resetFailedDialogStatus(currentDialog),
+                      characterReferences: (
+                        currentDialog.characterReferences ?? []
+                      ).filter((item) => item.id !== reference.id),
+                    }
+                  : currentDialog,
+              )
+            }
+          />
+        ))}
+        <ImageCanvasReferenceSlot
+          buttonRef={characterReferenceButtonRef}
+          tone="default"
+          icon={<ImagePlus className="h-4 w-4" aria-hidden="true" />}
+          label="参考图"
+          ariaLabel="上传常规参考图"
+          disabled={dialog.status === 'generating'}
+          isAdd
+          onClick={() => setIsCharacterReferenceMenuOpen((open) => !open)}
+        />
+        {isCharacterReferenceMenuOpen
+          ? renderEditorPortal(
+              <PlatformFloatingMenu
+                className="image-canvas-editor__character-spec-menu image-canvas-editor__portal-menu"
+                label="常规参考图来源"
+                placement="top-start"
+                style={buildPortalMenuStyle(
+                  characterReferenceButtonRef.current,
+                  'above',
+                )}
+              >
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsPickingCharacterReferenceFromCanvas(true);
+                    setIsCharacterReferenceMenuOpen(false);
+                  }}
+                >
+                  从画布中选择
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsCharacterReferenceMenuOpen(false);
+                    onRequestUpload('character-reference');
+                  }}
+                >
+                  上传图片
+                </PlatformFloatingMenuItem>
+              </PlatformFloatingMenu>,
+            )
+          : null}
+      </div>
+      <label className="image-canvas-editor__field-block image-canvas-editor__field-block--single">
+        <PlatformTextField
+          variant="textarea"
+          aria-label="角色设定"
+          value={dialog.prompt}
+          disabled={dialog.status === 'generating'}
+          placeholder="你希望角色如何设计？"
+          size="sm"
+          density="compact"
+          className="image-canvas-editor__generation-prompt image-canvas-editor__generation-prompt--borderless"
+          onChange={(event) =>
+            setGenerateDialog((currentDialog) =>
+              currentDialog?.mode === 'character'
+                ? {
+                    ...resetFailedDialogStatus(currentDialog),
+                    prompt: event.target.value,
+                  }
+                : currentDialog,
+            )
+          }
+        />
+      </label>
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+      <div className="image-canvas-editor__generation-composer-footer">
+        <ImageCanvasGenerationImageOptionsView
+          dialog={dialog}
+          setGenerateDialog={setGenerateDialog}
+          includeDimensions
+          onRememberImageModel={onRememberImageModel}
+          optionLabelPrefix="生成图片"
+          cost={calculateEditorImageGenerationPrice({
+            kind: 'character',
+            model: dialog.imageModel,
+          })}
+          submitLabel="生成"
+          submitAriaLabel="生成"
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+        />
+      </div>
+    </form>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasContextMenusView.test.tsx b/src/components/image-editor/ImageCanvasContextMenusView.test.tsx
new file mode 100644
index 000000000..5abcdff90
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasContextMenusView.test.tsx
@@ -0,0 +1,137 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { ImageCanvasContextMenusView } from './ImageCanvasContextMenusView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '角色图',
+    src: 'data:image/png;base64,layer',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function renderContextMenus(
+  overrides: Partial<Parameters<typeof ImageCanvasContextMenusView>[0]> = {},
+) {
+  const props: Parameters<typeof ImageCanvasContextMenusView>[0] = {
+    viewport: { x: 0, y: 0, scale: 1 },
+    contextMenu: null,
+    canvasClipboard: null,
+    imageContextMenu: null,
+    imageContextMenuLayer: null,
+    contextShouldShowLayer: false,
+    contextShouldUnlockLayer: false,
+    onPasteCanvasClipboard: vi.fn(),
+    onCopyContextLayers: vi.fn(),
+    onDuplicateContextLayers: vi.fn(),
+    onMoveContextLayers: vi.fn(),
+    onGroupContextLayers: vi.fn(),
+    onUngroupContextLayers: vi.fn(),
+    onToggleContextLayerVisibility: vi.fn(),
+    onToggleContextLayerLock: vi.fn(),
+    onFlipContextLayers: vi.fn(),
+    onExportContextLayer: vi.fn(),
+    onDeleteContextLayers: vi.fn(),
+    onDeleteLayerById: vi.fn(),
+    onCloseContextMenu: vi.fn(),
+    onCloseImageContextMenu: vi.fn(),
+    onUpdateScaleFromCenter: vi.fn(),
+    onFitLayers: vi.fn(),
+    onOpenQuickEditPanel: vi.fn(),
+    onOpenLayerMetadata: vi.fn(),
+    onOpenCharacterAnimationPanel: vi.fn(),
+    ...overrides,
+  };
+
+  render(<ImageCanvasContextMenusView {...props} />);
+
+  return props;
+}
+
+describe('ImageCanvasContextMenusView', () => {
+  it('renders blank canvas commands and forwards the canvas point', () => {
+    const canvasPoint = { x: 18, y: 24 };
+    const layer = createLayer();
+    const props = renderContextMenus({
+      contextMenu: { kind: 'blank', x: 10, y: 12, canvasPoint },
+      canvasClipboard: { layers: [layer], mode: 'copy' },
+    });
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '粘贴' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '放大' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '显示画布所有元素' }));
+
+    expect(props.onPasteCanvasClipboard).toHaveBeenCalledWith(canvasPoint);
+    expect(props.onUpdateScaleFromCenter).toHaveBeenCalledWith(1.16);
+    expect(props.onFitLayers).toHaveBeenCalledTimes(1);
+    expect(props.onCloseContextMenu).toHaveBeenCalledTimes(2);
+  });
+
+  it('renders layer context commands and forwards layer operations', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const props = renderContextMenus({
+      contextMenu: {
+        kind: 'layer',
+        x: 16,
+        y: 18,
+        layerId: layer.id,
+        canvasPoint: { x: 40, y: 42 },
+      },
+      canvasClipboard: { layers: [layer], mode: 'copy' },
+      imageContextMenuLayer: layer,
+      contextShouldShowLayer: true,
+      contextShouldUnlockLayer: true,
+    });
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '复制' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '剪切' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '创建副本' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '上移一层' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '显示' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '解锁' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '水平翻转' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '生成动画' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '删除' }));
+
+    expect(props.onCopyContextLayers).toHaveBeenNthCalledWith(1);
+    expect(props.onCopyContextLayers).toHaveBeenNthCalledWith(2, { cut: true });
+    expect(props.onDuplicateContextLayers).toHaveBeenCalledTimes(1);
+    expect(props.onMoveContextLayers).toHaveBeenCalledWith('up');
+    expect(props.onToggleContextLayerVisibility).toHaveBeenCalledTimes(1);
+    expect(props.onToggleContextLayerLock).toHaveBeenCalledTimes(1);
+    expect(props.onFlipContextLayers).toHaveBeenCalledWith('x');
+    expect(props.onOpenCharacterAnimationPanel).toHaveBeenCalledWith(layer);
+    expect(props.onDeleteContextLayers).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the image context menu when no canvas context menu is open', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const props = renderContextMenus({
+      imageContextMenu: { layerId: layer.id, x: 20, y: 22 },
+      imageContextMenuLayer: layer,
+    });
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '快速编辑' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '查看图片信息' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '删除图片' }));
+
+    expect(props.onOpenQuickEditPanel).toHaveBeenCalledWith(layer);
+    expect(props.onOpenLayerMetadata).toHaveBeenCalledWith(layer);
+    expect(props.onCloseImageContextMenu).toHaveBeenCalledTimes(1);
+    expect(props.onDeleteLayerById).toHaveBeenCalledWith(layer.id);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasContextMenusView.tsx b/src/components/image-editor/ImageCanvasContextMenusView.tsx
new file mode 100644
index 000000000..e3b9019c0
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasContextMenusView.tsx
@@ -0,0 +1,319 @@
+import { PlatformFloatingMenu, PlatformFloatingMenuItem } from '../common/PlatformFloatingMenu';
+import type {
+  CanvasClipboard,
+  CanvasContextMenuState,
+  CanvasLayer,
+  CanvasViewport,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+
+type ImageCanvasContextMenusViewProps = {
+  viewport: CanvasViewport;
+  contextMenu: CanvasContextMenuState | null;
+  canvasClipboard: CanvasClipboard | null;
+  imageContextMenu: ImageContextMenuState | null;
+  imageContextMenuLayer: CanvasLayer | null;
+  contextShouldShowLayer: boolean;
+  contextShouldUnlockLayer: boolean;
+  onPasteCanvasClipboard: (canvasPoint?: { x: number; y: number }) => void;
+  onCopyContextLayers: (options?: { cut?: boolean }) => void;
+  onDuplicateContextLayers: () => void;
+  onMoveContextLayers: (mode: 'up' | 'down' | 'top' | 'bottom') => void;
+  onGroupContextLayers: () => void;
+  onUngroupContextLayers: () => void;
+  onToggleContextLayerVisibility: () => void;
+  onToggleContextLayerLock: () => void;
+  onFlipContextLayers: (axis: 'x' | 'y') => void;
+  onExportContextLayer: () => void;
+  onDeleteContextLayers: () => void;
+  onDeleteLayerById: (layerId: string | null) => void;
+  onCloseContextMenu: () => void;
+  onCloseImageContextMenu: () => void;
+  onUpdateScaleFromCenter: (nextScale: number) => void;
+  onFitLayers: () => void;
+  onOpenQuickEditPanel: (layer: CanvasLayer) => void;
+  onOpenLayerMetadata: (layer: CanvasLayer) => void;
+  onOpenCharacterAnimationPanel: (layer: CanvasLayer) => void;
+};
+
+export function ImageCanvasContextMenusView({
+  viewport,
+  contextMenu,
+  canvasClipboard,
+  imageContextMenu,
+  imageContextMenuLayer,
+  contextShouldShowLayer,
+  contextShouldUnlockLayer,
+  onPasteCanvasClipboard,
+  onCopyContextLayers,
+  onDuplicateContextLayers,
+  onMoveContextLayers,
+  onGroupContextLayers,
+  onUngroupContextLayers,
+  onToggleContextLayerVisibility,
+  onToggleContextLayerLock,
+  onFlipContextLayers,
+  onExportContextLayer,
+  onDeleteContextLayers,
+  onDeleteLayerById,
+  onCloseContextMenu,
+  onCloseImageContextMenu,
+  onUpdateScaleFromCenter,
+  onFitLayers,
+  onOpenQuickEditPanel,
+  onOpenLayerMetadata,
+  onOpenCharacterAnimationPanel,
+}: ImageCanvasContextMenusViewProps) {
+  return (
+    <>
+      {contextMenu ? (
+        <div
+          className="image-canvas-editor__context-menu"
+          role="menu"
+          aria-label={
+            contextMenu.kind === 'blank' ? '画布右键菜单' : '图片功能面板'
+          }
+          style={{
+            left: contextMenu.x,
+            top: contextMenu.y,
+          }}
+          onContextMenu={(event) => event.preventDefault()}
+          onPointerDown={(event) => event.stopPropagation()}
+        >
+          {contextMenu.kind === 'blank' ? (
+            <>
+              <button
+                type="button"
+                role="menuitem"
+                disabled={!canvasClipboard?.layers.length}
+                onClick={() => onPasteCanvasClipboard(contextMenu.canvasPoint)}
+              >
+                粘贴
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => {
+                  onUpdateScaleFromCenter(viewport.scale * 1.16);
+                  onCloseContextMenu();
+                }}
+              >
+                放大
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => {
+                  onUpdateScaleFromCenter(viewport.scale * 0.86);
+                  onCloseContextMenu();
+                }}
+              >
+                缩小
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => {
+                  onFitLayers();
+                  onCloseContextMenu();
+                }}
+              >
+                显示画布所有元素
+              </button>
+            </>
+          ) : (
+            <>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onCopyContextLayers()}
+              >
+                复制
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onCopyContextLayers({ cut: true })}
+              >
+                剪切
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                disabled={!canvasClipboard?.layers.length}
+                onClick={() => onPasteCanvasClipboard(contextMenu.canvasPoint)}
+              >
+                粘贴
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={onDuplicateContextLayers}
+              >
+                创建副本
+              </button>
+              <hr />
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onMoveContextLayers('up')}
+              >
+                上移一层
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onMoveContextLayers('down')}
+              >
+                下移一层
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onMoveContextLayers('top')}
+              >
+                置于顶层
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onMoveContextLayers('bottom')}
+              >
+                移动至底层
+              </button>
+              <hr />
+              <button type="button" role="menuitem" onClick={onGroupContextLayers}>
+                创建组
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={onUngroupContextLayers}
+              >
+                解除组
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={onToggleContextLayerVisibility}
+              >
+                {contextShouldShowLayer ? '显示' : '隐藏'}
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={onToggleContextLayerLock}
+              >
+                {contextShouldUnlockLayer ? '解锁' : '锁定'}
+              </button>
+              <hr />
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onFlipContextLayers('x')}
+              >
+                水平翻转
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                onClick={() => onFlipContextLayers('y')}
+              >
+                垂直翻转
+              </button>
+              <button type="button" role="menuitem" onClick={onExportContextLayer}>
+                导出为
+              </button>
+              <hr />
+              {imageContextMenuLayer ? (
+                <>
+                  <button
+                    type="button"
+                    role="menuitem"
+                    onClick={() => onOpenQuickEditPanel(imageContextMenuLayer)}
+                  >
+                    快速编辑
+                  </button>
+                  <button
+                    type="button"
+                    role="menuitem"
+                    onClick={() => {
+                      onOpenLayerMetadata(imageContextMenuLayer);
+                      onCloseContextMenu();
+                      onCloseImageContextMenu();
+                    }}
+                  >
+                    查看图片信息
+                  </button>
+                  {imageContextMenuLayer.assetKind === 'character' ? (
+                    <button
+                      type="button"
+                      role="menuitem"
+                      onClick={() =>
+                        onOpenCharacterAnimationPanel(imageContextMenuLayer)
+                      }
+                    >
+                      生成动画
+                    </button>
+                  ) : null}
+                  <hr />
+                </>
+              ) : null}
+              <button
+                type="button"
+                role="menuitem"
+                className="image-canvas-editor__context-menu-danger"
+                onClick={onDeleteContextLayers}
+              >
+                删除
+              </button>
+            </>
+          )}
+        </div>
+      ) : null}
+
+      {imageContextMenu && imageContextMenuLayer && !contextMenu ? (
+        <div
+          className="image-canvas-editor__context-menu"
+          style={{
+            left: imageContextMenu.x,
+            top: imageContextMenu.y,
+          }}
+          onPointerDown={(event) => event.stopPropagation()}
+        >
+          <PlatformFloatingMenu label="图片功能面板" placement="bottom-start">
+            <PlatformFloatingMenuItem
+              className="image-canvas-editor__context-menu-item"
+              onClick={() => onOpenQuickEditPanel(imageContextMenuLayer)}
+            >
+              快速编辑
+            </PlatformFloatingMenuItem>
+            <PlatformFloatingMenuItem
+              className="image-canvas-editor__context-menu-item"
+              onClick={() => {
+                onOpenLayerMetadata(imageContextMenuLayer);
+                onCloseImageContextMenu();
+              }}
+            >
+              查看图片信息
+            </PlatformFloatingMenuItem>
+            {imageContextMenuLayer.assetKind === 'character' ? (
+              <PlatformFloatingMenuItem
+                className="image-canvas-editor__context-menu-item"
+                onClick={() => onOpenCharacterAnimationPanel(imageContextMenuLayer)}
+              >
+                生成动画
+              </PlatformFloatingMenuItem>
+            ) : null}
+            <PlatformFloatingMenuItem
+              className="image-canvas-editor__context-menu-item"
+              onClick={() => onDeleteLayerById(imageContextMenuLayer.id)}
+            >
+              删除图片
+            </PlatformFloatingMenuItem>
+          </PlatformFloatingMenu>
+        </div>
+      ) : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasCropExpandModel.test.ts b/src/components/image-editor/ImageCanvasCropExpandModel.test.ts
new file mode 100644
index 000000000..68e4b3f9f
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCropExpandModel.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import { resizeCropExpandFrame } from './ImageCanvasCropExpandModel';
+
+describe('ImageCanvasCropExpandModel', () => {
+  it('resizes crop-expand frame freely from canvas handles', () => {
+    expect(
+      resizeCropExpandFrame({
+        frame: { x: 100, y: 80, width: 200, height: 120 },
+        handle: 'right',
+        deltaX: 40,
+        deltaY: 0,
+        ratio: 'free',
+      }),
+    ).toEqual({ x: 100, y: 80, width: 240, height: 120 });
+  });
+
+  it('keeps a fixed ratio while dragging a crop-expand handle', () => {
+    const frame = resizeCropExpandFrame({
+      frame: { x: 100, y: 80, width: 200, height: 120 },
+      handle: 'bottom-right',
+      deltaX: 80,
+      deltaY: 10,
+      ratio: '1:1',
+    });
+
+    expect(frame.width).toBe(frame.height);
+    expect(frame).toEqual({ x: 100, y: 80, width: 280, height: 280 });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasCropExpandModel.ts b/src/components/image-editor/ImageCanvasCropExpandModel.ts
new file mode 100644
index 000000000..6422a1a60
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCropExpandModel.ts
@@ -0,0 +1,184 @@
+import type {
+  CropExpandPanelState,
+  CropExpandResizeHandle,
+  CropExpandRatioValue,
+} from './ImageCanvasEditorTypes';
+
+export const CROP_EXPAND_MIN_FRAME_SIZE = 16;
+
+type CropExpandFrame = CropExpandPanelState['frame'];
+
+type ResizeCropExpandFrameOptions = {
+  frame: CropExpandFrame;
+  handle: CropExpandResizeHandle;
+  deltaX: number;
+  deltaY: number;
+  ratio: CropExpandRatioValue;
+  minSize?: number;
+};
+
+export function resolveCropExpandRatioNumber(
+  ratio: CropExpandRatioValue,
+): number | null {
+  if (ratio === 'free') {
+    return null;
+  }
+  const [widthValue, heightValue] = ratio.split(':').map(Number);
+  if (!widthValue || !heightValue) {
+    return null;
+  }
+  return widthValue / heightValue;
+}
+
+function normalizeFreeFrame(frame: CropExpandFrame, minSize: number) {
+  const right = frame.x + frame.width;
+  const bottom = frame.y + frame.height;
+  return {
+    x: Math.min(frame.x, right - minSize),
+    y: Math.min(frame.y, bottom - minSize),
+    width: Math.max(minSize, frame.width),
+    height: Math.max(minSize, frame.height),
+  };
+}
+
+function buildFreeResizeFrame({
+  frame,
+  handle,
+  deltaX,
+  deltaY,
+  minSize,
+}: Omit<ResizeCropExpandFrameOptions, 'ratio'> & {
+  minSize: number;
+}): CropExpandFrame {
+  const nextFrame = { ...frame };
+  const right = frame.x + frame.width;
+  const bottom = frame.y + frame.height;
+
+  if (handle.includes('left')) {
+    nextFrame.x = Math.min(frame.x + deltaX, right - minSize);
+    nextFrame.width = right - nextFrame.x;
+  }
+  if (handle.includes('right')) {
+    nextFrame.width = Math.max(minSize, frame.width + deltaX);
+  }
+  if (handle.includes('top')) {
+    nextFrame.y = Math.min(frame.y + deltaY, bottom - minSize);
+    nextFrame.height = bottom - nextFrame.y;
+  }
+  if (handle.includes('bottom')) {
+    nextFrame.height = Math.max(minSize, frame.height + deltaY);
+  }
+
+  return normalizeFreeFrame(nextFrame, minSize);
+}
+
+function resolveFixedDimensions({
+  candidate,
+  ratio,
+  minSize,
+}: {
+  candidate: CropExpandFrame;
+  ratio: number;
+  minSize: number;
+}) {
+  const widthFromHeight = Math.max(minSize, candidate.height * ratio);
+  const heightFromWidth = Math.max(minSize, candidate.width / ratio);
+  const optionFromWidth = {
+    width: Math.max(minSize, candidate.width),
+    height: heightFromWidth,
+  };
+  const optionFromHeight = {
+    width: widthFromHeight,
+    height: Math.max(minSize, candidate.height),
+  };
+  const widthDistance =
+    Math.abs(optionFromWidth.width - candidate.width) +
+    Math.abs(optionFromWidth.height - candidate.height);
+  const heightDistance =
+    Math.abs(optionFromHeight.width - candidate.width) +
+    Math.abs(optionFromHeight.height - candidate.height);
+  return widthDistance <= heightDistance ? optionFromWidth : optionFromHeight;
+}
+
+export function resizeCropExpandFrame({
+  frame,
+  handle,
+  deltaX,
+  deltaY,
+  ratio,
+  minSize = CROP_EXPAND_MIN_FRAME_SIZE,
+}: ResizeCropExpandFrameOptions): CropExpandFrame {
+  const freeFrame = buildFreeResizeFrame({
+    frame,
+    handle,
+    deltaX,
+    deltaY,
+    minSize,
+  });
+  const ratioNumber = resolveCropExpandRatioNumber(ratio);
+  if (!ratioNumber) {
+    return freeFrame;
+  }
+
+  const sourceRight = frame.x + frame.width;
+  const sourceBottom = frame.y + frame.height;
+  const sourceCenterX = frame.x + frame.width / 2;
+  const sourceCenterY = frame.y + frame.height / 2;
+  const dimensions = resolveFixedDimensions({
+    candidate: freeFrame,
+    ratio: ratioNumber,
+    minSize,
+  });
+
+  switch (handle) {
+    case 'left':
+      return {
+        x: sourceRight - dimensions.width,
+        y: sourceCenterY - dimensions.height / 2,
+        ...dimensions,
+      };
+    case 'right':
+      return {
+        x: frame.x,
+        y: sourceCenterY - dimensions.height / 2,
+        ...dimensions,
+      };
+    case 'top':
+      return {
+        x: sourceCenterX - dimensions.width / 2,
+        y: sourceBottom - dimensions.height,
+        ...dimensions,
+      };
+    case 'bottom':
+      return {
+        x: sourceCenterX - dimensions.width / 2,
+        y: frame.y,
+        ...dimensions,
+      };
+    case 'top-left':
+      return {
+        x: sourceRight - dimensions.width,
+        y: sourceBottom - dimensions.height,
+        ...dimensions,
+      };
+    case 'top-right':
+      return {
+        x: frame.x,
+        y: sourceBottom - dimensions.height,
+        ...dimensions,
+      };
+    case 'bottom-left':
+      return {
+        x: sourceRight - dimensions.width,
+        y: frame.y,
+        ...dimensions,
+      };
+    case 'bottom-right':
+    default:
+      return {
+        x: frame.x,
+        y: frame.y,
+        ...dimensions,
+      };
+  }
+}
diff --git a/src/components/image-editor/ImageCanvasCropExpandPanelView.tsx b/src/components/image-editor/ImageCanvasCropExpandPanelView.tsx
new file mode 100644
index 000000000..af728a271
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasCropExpandPanelView.tsx
@@ -0,0 +1,120 @@
+import { type CSSProperties, type Dispatch, type SetStateAction } from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import type {
+  CropExpandPanelState,
+  CropExpandRatioValue,
+} from './ImageCanvasEditorTypes';
+
+type ImageCanvasCropExpandPanelViewProps = {
+  panel: CropExpandPanelState;
+  style: CSSProperties;
+  setCropExpandPanel: Dispatch<SetStateAction<CropExpandPanelState | null>>;
+  onSubmit: () => void;
+};
+
+const CROP_EXPAND_RATIO_OPTIONS: Array<{
+  value: CropExpandRatioValue;
+  label: string;
+  shape?: 'square' | 'landscape' | 'portrait';
+}> = [
+  { value: 'free', label: '自由比例' },
+  { value: '1:1', label: '1:1', shape: 'square' },
+  { value: '4:3', label: '4:3', shape: 'landscape' },
+  { value: '3:4', label: '3:4', shape: 'portrait' },
+  { value: '16:9', label: '16:9', shape: 'landscape' },
+  { value: '9:16', label: '9:16', shape: 'portrait' },
+] as const;
+
+function resetFailedCropExpandPanel(panel: CropExpandPanelState) {
+  return {
+    ...panel,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+  };
+}
+
+export function ImageCanvasCropExpandPanelView({
+  panel,
+  style,
+  setCropExpandPanel,
+  onSubmit,
+}: ImageCanvasCropExpandPanelViewProps) {
+  return (
+    <form
+      className="image-canvas-editor__crop-expand-panel"
+      style={style}
+      role="dialog"
+      aria-label="裁扩图片"
+      onPointerDown={(event) => event.stopPropagation()}
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (panel.status !== 'processing') {
+          onSubmit();
+        }
+      }}
+    >
+      <div className="image-canvas-editor__crop-expand-head">
+        <strong>裁扩</strong>
+      </div>
+      <div className="image-canvas-editor__crop-expand-ratios">
+        {CROP_EXPAND_RATIO_OPTIONS.map((option) => (
+          <button
+            key={option.value}
+            type="button"
+            className={`image-canvas-editor__crop-expand-ratio ${
+              panel.ratio === option.value
+                ? 'image-canvas-editor__crop-expand-ratio--selected'
+                : ''
+            }`}
+            aria-pressed={panel.ratio === option.value}
+            onClick={() =>
+              setCropExpandPanel((currentPanel) =>
+                currentPanel
+                  ? {
+                      ...resetFailedCropExpandPanel(currentPanel),
+                      ratio: option.value,
+                    }
+                  : currentPanel,
+              )
+            }
+          >
+            <span
+              className={`image-canvas-editor__crop-expand-ratio-shape ${
+                option.shape
+                  ? `image-canvas-editor__crop-expand-ratio-shape--${option.shape}`
+                  : ''
+              }`}
+              aria-hidden="true"
+            />
+            <span>{option.label}</span>
+          </button>
+        ))}
+      </div>
+      {panel.status === 'failed' ? (
+        <p className="image-canvas-editor__crop-expand-error" role="alert">
+          {panel.errorMessage}
+        </p>
+      ) : null}
+      <div className="image-canvas-editor__crop-expand-actions">
+        <PlatformActionButton
+          type="button"
+          tone="secondary"
+          size="sm"
+          disabled={panel.status === 'processing'}
+          onClick={() => setCropExpandPanel(null)}
+        >
+          取消
+        </PlatformActionButton>
+        <PlatformActionButton
+          type="submit"
+          tone="primary"
+          size="sm"
+          disabled={panel.status === 'processing'}
+        >
+          {panel.status === 'processing' ? '处理中' : '完成'}
+        </PlatformActionButton>
+      </div>
+    </form>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx b/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx
new file mode 100644
index 000000000..8b2d1db02
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditGenerationModalView.test.tsx
@@ -0,0 +1,98 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
+import { ImageCanvasEditGenerationModalView } from './ImageCanvasEditGenerationModalView';
+
+function createDialog(
+  patch: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'edit',
+    prompt: '旧修改提示',
+    status: 'idle',
+    sourceLayerId: 'layer-a',
+    ...patch,
+  };
+}
+
+function EditGenerationModalHarness({
+  initialDialog = createDialog(),
+  onSubmit = vi.fn(),
+}: {
+  initialDialog?: GenerateDialogState | null;
+  onSubmit?: (dialog: GenerateDialogState) => void;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+
+  return (
+    <div>
+      <ImageCanvasEditGenerationModalView
+        dialog={dialog}
+        setGenerateDialog={setDialog}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="弹窗状态">{dialog ? 'open' : 'closed'}</output>
+      <output aria-label="当前提示词">{dialog?.prompt ?? '-'}</output>
+    </div>
+  );
+}
+
+describe('ImageCanvasEditGenerationModalView', () => {
+  it('updates prompt and submits edit generation', () => {
+    const submitEdit = vi.fn();
+    render(<EditGenerationModalHarness onSubmit={submitEdit} />);
+
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '新的修改提示' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '修改' }));
+
+    expect(screen.getByLabelText('当前提示词').textContent).toBe(
+      '新的修改提示',
+    );
+    expect(submitEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: '新的修改提示' }),
+    );
+  });
+
+  it('renders failure state and closes through the modal close button', () => {
+    render(
+      <EditGenerationModalHarness
+        initialDialog={createDialog({
+          status: 'failed',
+          errorMessage: '修改失败',
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('alert').textContent).toContain('修改失败');
+
+    fireEvent.click(screen.getByRole('button', { name: '关闭修改图片' }));
+
+    expect(screen.getByLabelText('弹窗状态').textContent).toBe('closed');
+  });
+
+  it('stays hidden for non-edit dialogs and generating edit dialogs', () => {
+    const { rerender } = render(
+      <EditGenerationModalHarness
+        initialDialog={createDialog({ mode: 'generate' })}
+      />,
+    );
+
+    expect(screen.queryByRole('dialog', { name: '修改图片' })).toBeNull();
+
+    rerender(
+      <EditGenerationModalHarness
+        initialDialog={createDialog({ status: 'generating' })}
+      />,
+    );
+
+    expect(screen.queryByRole('dialog', { name: '修改图片' })).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx b/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx
new file mode 100644
index 000000000..2f7027b79
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditGenerationModalView.tsx
@@ -0,0 +1,99 @@
+import { type Dispatch, type SetStateAction } from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { UnifiedModal } from '../common/UnifiedModal';
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
+
+type ImageCanvasEditGenerationModalViewProps = {
+  dialog: GenerateDialogState | null;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+
+export function ImageCanvasEditGenerationModalView({
+  dialog,
+  setGenerateDialog,
+  onSubmit,
+}: ImageCanvasEditGenerationModalViewProps) {
+  const isOpen = dialog?.mode === 'edit' && dialog.status !== 'generating';
+
+  return (
+    <UnifiedModal
+      open={isOpen}
+      title={dialog?.mode === 'edit' ? '修改图片' : '生成图片'}
+      size="sm"
+      closeLabel={dialog?.mode === 'edit' ? '关闭修改图片' : '关闭生成图片'}
+      closeDisabled={dialog?.status === 'generating'}
+      onClose={() => setGenerateDialog(null)}
+      panelClassName="image-canvas-editor__generate-dialog"
+      bodyClassName="image-canvas-editor__generate-dialog-body"
+    >
+      {dialog?.mode === 'edit' ? (
+        <form
+          className="image-canvas-editor__generate-form"
+          onSubmit={(event) => {
+            event.preventDefault();
+            if (dialog.status !== 'generating') {
+              onSubmit(dialog);
+            }
+          }}
+        >
+          <div className="image-canvas-editor__generate-body">
+            <PlatformTextField
+              variant="textarea"
+              aria-label="生成提示词"
+              value={dialog.prompt}
+              disabled={dialog.status === 'generating'}
+              size="sm"
+              density="roomy"
+              className="image-canvas-editor__generate-prompt"
+              placeholder="描述你想如何修改这张图片"
+              onChange={(event) =>
+                setGenerateDialog((currentDialog) =>
+                  currentDialog
+                    ? {
+                        ...currentDialog,
+                        prompt: event.target.value,
+                      }
+                    : currentDialog,
+                )
+              }
+            />
+            {dialog.status === 'generating' ? (
+              <PlatformStatusMessage
+                tone="info"
+                surface="platform"
+                size="xs"
+                className="image-canvas-editor__generate-status"
+                role="status"
+              >
+                修改中
+              </PlatformStatusMessage>
+            ) : null}
+            {dialog.status === 'failed' ? (
+              <PlatformStatusMessage
+                tone="error"
+                surface="platform"
+                size="xs"
+                className="image-canvas-editor__generate-status"
+                role="alert"
+              >
+                {dialog.errorMessage}
+              </PlatformStatusMessage>
+            ) : null}
+            <PlatformActionButton
+              type="submit"
+              size="sm"
+              className="image-canvas-editor__generate-submit"
+              disabled={dialog.status === 'generating'}
+            >
+              {dialog.status === 'generating' ? '修改中' : '修改'}
+            </PlatformActionButton>
+          </div>
+        </form>
+      ) : null}
+    </UnifiedModal>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx
new file mode 100644
index 000000000..af77f2b38
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx
@@ -0,0 +1,1055 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  ApiClientError,
+  AuthUiContext,
+  ImageCanvasEditorView,
+  createAuthValue,
+  createDataTransferStub,
+  createDeferred,
+  dispatchPointerEvent,
+  setupImageCanvasEditorViewTestLifecycle,
+} from './ImageCanvasEditorView.test-utils';
+
+const generateEditorImageMock = vi.hoisted(() => vi.fn());
+const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
+const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
+const editEditorImageMock = vi.hoisted(() => vi.fn());
+const createEditorAssetMock = vi.hoisted(() => vi.fn());
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const createEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetMock = vi.hoisted(() => vi.fn());
+const loadEditorAssetLibraryMock = vi.hoisted(() => vi.fn());
+const loadEditorProjectMock = vi.hoisted(() => vi.fn());
+const loadOrCreateRecentEditorProjectMock = vi.hoisted(() => vi.fn());
+const renameEditorProjectMock = vi.hoisted(() => vi.fn());
+const saveEditorProjectLayoutMock = vi.hoisted(() => vi.fn());
+const uploadEditorMediaAssetFileMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: editEditorImageMock,
+    createEditorAsset: createEditorAssetMock,
+    createEditorAssetFolder: createEditorAssetFolderMock,
+    createEditorProjectResource: createEditorProjectResourceMock,
+    deleteEditorAsset: deleteEditorAssetMock,
+    deleteEditorAssetFolder: deleteEditorAssetFolderMock,
+    generateEditorCharacterAnimation: generateEditorCharacterAnimationMock,
+    generateEditorIconSpritesheet: generateEditorIconSpritesheetMock,
+    generateEditorImage: generateEditorImageMock,
+    loadEditorAssetLibrary: loadEditorAssetLibraryMock,
+    loadEditorProject: loadEditorProjectMock,
+    loadOrCreateRecentEditorProject: loadOrCreateRecentEditorProjectMock,
+    renameEditorProject: renameEditorProjectMock,
+    saveEditorProjectLayout: saveEditorProjectLayoutMock,
+    updateEditorAsset: updateEditorAssetMock,
+    updateEditorAssetFolder: updateEditorAssetFolderMock,
+  };
+});
+
+vi.mock('../../services/image-editor/editorMediaAssetUploadClient', () => ({
+  uploadEditorMediaAssetFile: uploadEditorMediaAssetFileMock,
+}));
+
+function createSizedPngFile(name: string, width: number, height: number) {
+  const bytes = new Uint8Array([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    0,
+    0,
+    0,
+    13,
+    0x49,
+    0x48,
+    0x44,
+    0x52,
+    (width >> 24) & 0xff,
+    (width >> 16) & 0xff,
+    (width >> 8) & 0xff,
+    width & 0xff,
+    (height >> 24) & 0xff,
+    (height >> 16) & 0xff,
+    (height >> 8) & 0xff,
+    height & 0xff,
+    8,
+    6,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+  ]);
+  return new File([bytes], name, { type: 'image/png' });
+}
+
+describe('ImageCanvasEditorView asset library integration', () => {
+  setupImageCanvasEditorViewTestLifecycle({
+    generateEditorImageMock,
+    generateEditorIconSpritesheetMock,
+    generateEditorCharacterAnimationMock,
+    editEditorImageMock,
+    createEditorAssetMock,
+    createEditorProjectResourceMock,
+    createEditorAssetFolderMock,
+    updateEditorAssetMock,
+    updateEditorAssetFolderMock,
+    deleteEditorAssetFolderMock,
+    deleteEditorAssetMock,
+    loadEditorAssetLibraryMock,
+    loadEditorProjectMock,
+    loadOrCreateRecentEditorProjectMock,
+    renameEditorProjectMock,
+    saveEditorProjectLayoutMock,
+  });
+
+  beforeEach(() => {
+    uploadEditorMediaAssetFileMock.mockImplementation(
+      async (file: File, mediaType: 'video' | 'audio') => ({
+        src: `https://signed.example.com/editor/${mediaType}/${file.name}`,
+        legacyPublicPath: `/generated-character-drafts/editor/asset-library/${mediaType}/${file.name}`,
+        objectKey: `generated-character-drafts/editor/asset-library/${mediaType}/${file.name}`,
+        assetObjectId: `assetobj-editor-${mediaType}`,
+      }),
+    );
+  });
+
+  it('keeps only one default asset folder when the persisted library returns duplicated defaults', async () => {
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'legacy-project',
+          label: '旧项目素材',
+          sortOrder: 1,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    expect(
+      await screen.findByRole('region', { name: '项目素材' }),
+    ).toBeTruthy();
+    expect(screen.queryByRole('region', { name: '旧项目素材' })).toBeNull();
+    expect(screen.getAllByRole('button', { name: /上传到/u })).toHaveLength(1);
+  });
+
+  it('toggles the shared sidebar from canvas panel buttons', () => {
+    render(<ImageCanvasEditorView />);
+
+    const sidebar = screen.getByRole('complementary', { name: '图片资源栏' });
+    const panelToolbar = screen.getByRole('toolbar', { name: '画布面板入口' });
+    const assetsButton = within(panelToolbar).getByRole('button', {
+      name: '打开素材',
+    });
+    const layersButton = within(panelToolbar).getByRole('button', {
+      name: '打开图层',
+    });
+
+    expect(within(sidebar).getByText('素材')).toBeTruthy();
+    expect(
+      within(sidebar).getByRole('button', { name: '添加拼图素材' }),
+    ).toBeTruthy();
+    expect(assetsButton.getAttribute('aria-pressed')).toBe('true');
+    expect(screen.queryByRole('button', { name: '打开已生成文件' })).toBeNull();
+    expect(screen.queryByRole('button', { name: '收起素材栏' })).toBeNull();
+    expect(screen.queryByRole('button', { name: '展开素材栏' })).toBeNull();
+
+    fireEvent.click(layersButton);
+
+    const layerSidebar = screen.getByRole('complementary', {
+      name: '图片资源栏',
+    });
+    expect(within(layerSidebar).getByText('图层')).toBeTruthy();
+    expect(
+      within(layerSidebar).getByRole('button', { name: '选择图层拼图素材' }),
+    ).toBeTruthy();
+    expect(layersButton.getAttribute('aria-pressed')).toBe('true');
+    expect(screen.queryByRole('button', { name: '添加拼图素材' })).toBeNull();
+
+    fireEvent.click(layersButton);
+
+    expect(
+      screen.queryByRole('complementary', { name: '图片资源栏' }),
+    ).toBeNull();
+    expect(layersButton.getAttribute('aria-pressed')).toBe('false');
+  });
+
+  it('groups assets by folder and renames sidebar materials', async () => {
+    const user = userEvent.setup();
+    render(<ImageCanvasEditorView />);
+
+    const sidebar = screen.getByRole('complementary', { name: '图片资源栏' });
+    expect(
+      within(sidebar).getByRole('region', { name: '项目素材' }),
+    ).toBeTruthy();
+    expect(
+      within(sidebar).queryByRole('region', { name: '参考素材' }),
+    ).toBeNull();
+
+    await user.click(
+      screen.getByRole('button', { name: '重命名素材拼图素材' }),
+    );
+    const renameInput = screen.getByLabelText('重命名素材拼图素材');
+    await user.clear(renameInput);
+    await user.type(renameInput, '主视觉素材');
+    await user.click(
+      screen.getByRole('button', { name: '保存素材拼图素材名称' }),
+    );
+
+    expect(screen.queryByRole('button', { name: '添加拼图素材' })).toBeNull();
+    await user.click(screen.getByRole('button', { name: '添加主视觉素材' }));
+
+    expect(screen.getByAltText('画布图片：主视觉素材')).toBeTruthy();
+  });
+
+  it('collapses folders, creates upload folders, and deletes uploaded materials', async () => {
+    const user = userEvent.setup();
+    const createObjectUrlSpy = vi.fn(() => 'blob:folder-uploaded-image');
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: createObjectUrlSpy,
+    });
+    render(<ImageCanvasEditorView />);
+
+    await user.click(screen.getByRole('button', { name: '折叠项目素材' }));
+    expect(screen.queryByRole('button', { name: '添加拼图素材' })).toBeNull();
+    await user.click(screen.getByRole('button', { name: '展开项目素材' }));
+    expect(screen.getByRole('button', { name: '添加拼图素材' })).toBeTruthy();
+
+    await user.click(screen.getByRole('button', { name: '新建素材文件夹' }));
+    const folderNameInput = screen.getByLabelText('素材文件夹名称');
+    await user.type(folderNameInput, '角色上传');
+    await user.click(screen.getByRole('button', { name: '保存素材文件夹' }));
+
+    const uploadInput = screen.getByLabelText('上传媒体文件');
+    await user.click(screen.getByRole('button', { name: '上传到角色上传' }));
+    await userEvent.upload(
+      uploadInput,
+      new File(['image'], '角色草图.png', { type: 'image/png' }),
+    );
+
+    const customFolder = screen.getByRole('region', { name: '角色上传' });
+    await waitFor(() => {
+      expect(
+        within(customFolder).getByRole('button', { name: '添加角色草图.png' }),
+      ).toBeTruthy();
+      expect(
+        within(customFolder).getByRole('button', {
+          name: '删除素材角色草图.png',
+        }),
+      ).toBeTruthy();
+    });
+
+    await user.click(
+      within(customFolder).getByRole('button', {
+        name: '删除素材角色草图.png',
+      }),
+    );
+
+    expect(
+      screen.queryByRole('button', { name: '添加角色草图.png' }),
+    ).toBeNull();
+    expect(screen.queryByAltText('画布图片：角色草图.png')).toBeNull();
+  });
+
+  it('renames and deletes asset folders through the persisted asset library API', async () => {
+    const user = userEvent.setup();
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'folder-role',
+          label: '角色',
+          sortOrder: 100,
+          collapsed: false,
+          systemDefault: false,
+        },
+      ],
+      assets: [],
+    });
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByRole('region', { name: '角色' });
+    await user.click(screen.getByRole('button', { name: '重命名文件夹角色' }));
+    const folderRenameInput = screen.getByLabelText('重命名文件夹角色');
+    await user.clear(folderRenameInput);
+    await user.type(folderRenameInput, '角色参考');
+    await user.click(
+      screen.getByRole('button', { name: '保存文件夹角色名称' }),
+    );
+
+    expect(updateEditorAssetFolderMock).toHaveBeenCalledWith('folder-role', {
+      label: '角色参考',
+    });
+
+    await user.click(
+      screen.getByRole('button', { name: '删除文件夹角色参考' }),
+    );
+
+    expect(deleteEditorAssetFolderMock).toHaveBeenCalledWith('folder-role');
+  });
+
+  it('moves an asset to another folder when dragging inside the asset library', async () => {
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'folder-role',
+          label: '角色',
+          sortOrder: 100,
+          collapsed: false,
+          systemDefault: false,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-puzzle',
+          folderId: 'project',
+          label: '拼图素材',
+          imageSrc: '/creation-type-references/puzzle.webp',
+          width: 640,
+          height: 640,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    const sourceAsset = await screen.findByRole('button', {
+      name: '添加拼图素材',
+    });
+    const sourceAssetRow = sourceAsset.closest(
+      '.image-canvas-editor__asset-row',
+    );
+    const projectFolder = screen.getByRole('region', { name: '项目素材' });
+    const roleFolder = screen.getByRole('region', { name: '角色' });
+    const dataTransfer = createDataTransferStub();
+
+    if (!sourceAssetRow) {
+      throw new Error('asset row should exist');
+    }
+    fireEvent.dragStart(sourceAssetRow, { dataTransfer });
+    fireEvent.dragOver(roleFolder, { dataTransfer });
+    await waitFor(() => {
+      expect(screen.queryByText('添加到素材')).toBeNull();
+      expect(roleFolder.className).toContain(
+        'image-canvas-editor__asset-folder--move-target',
+      );
+    });
+    fireEvent.drop(roleFolder, { dataTransfer });
+
+    expect(updateEditorAssetMock).toHaveBeenCalledWith('asset-puzzle', {
+      folderId: 'folder-role',
+    });
+    expect(
+      within(projectFolder).queryByRole('button', { name: '添加拼图素材' }),
+    ).toBeNull();
+    expect(
+      within(roleFolder).getByRole('button', { name: '添加拼图素材' }),
+    ).toBeTruthy();
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+  });
+
+  it('uploads multiple files as account-level assets without adding canvas layers', async () => {
+    render(<ImageCanvasEditorView />);
+
+    await userEvent.upload(screen.getByLabelText('上传媒体文件'), [
+      new File(['image-a'], '第一张.png', { type: 'image/png' }),
+      new File(['image-b'], '第二张.png', { type: 'image/png' }),
+    ]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: '添加第一张.png' }),
+      ).toBeTruthy();
+      expect(
+        screen.getByRole('button', { name: '添加第二张.png' }),
+      ).toBeTruthy();
+    });
+    expect(createEditorAssetMock).toHaveBeenCalledTimes(2);
+    expect(screen.queryByAltText('画布图片：第一张.png')).toBeNull();
+    expect(screen.queryByAltText('画布图片：第二张.png')).toBeNull();
+  });
+
+  it('adds bottom toolbar uploads to the canvas using the image resolution', async () => {
+    const user = userEvent.setup();
+    render(<ImageCanvasEditorView />);
+
+    await user.click(screen.getByRole('button', { name: '上传工具' }));
+    await userEvent.upload(
+      screen.getByLabelText('上传媒体文件'),
+      createSizedPngFile('底栏上传.png', 1536, 1024),
+    );
+
+    expect(await screen.findByAltText('画布图片：底栏上传.png')).toBeTruthy();
+    await waitFor(() => {
+      expect(createEditorAssetMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          label: '底栏上传.png',
+          width: 1536,
+          height: 1024,
+        }),
+      );
+    });
+    const layerButton = screen.getByRole('button', {
+      name: '选择底栏上传.png',
+    });
+    expect(layerButton.getAttribute('style')).toContain('width: 1536px');
+    expect(layerButton.getAttribute('style')).toContain('height: 1024px');
+  });
+
+  it('uploads MP3 and MP4 files through OSS before adding them to the asset library', async () => {
+    const createdMediaElements: HTMLMediaElement[] = [];
+    const originalCreateElement = document.createElement.bind(document);
+    vi.spyOn(document, 'createElement').mockImplementation((tagName, options) => {
+      const element = originalCreateElement(tagName, options);
+      if (tagName === 'video' || tagName === 'audio') {
+        createdMediaElements.push(element as HTMLMediaElement);
+      }
+      return element;
+    });
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: vi.fn(() => 'blob:editor-media'),
+    });
+    Object.defineProperty(URL, 'revokeObjectURL', {
+      configurable: true,
+      value: vi.fn(),
+    });
+    Object.defineProperty(HTMLMediaElement.prototype, 'duration', {
+      configurable: true,
+      value: 6,
+    });
+    vi.spyOn(HTMLMediaElement.prototype, 'load').mockImplementation(
+      () => undefined,
+    );
+    render(<ImageCanvasEditorView />);
+
+    await userEvent.upload(screen.getByLabelText('上传媒体文件'), [
+      new File(['audio'], '胜利音效.mp3', { type: 'audio/mpeg' }),
+      new File(['video'], '开场动画.mp4', { type: 'video/mp4' }),
+    ]);
+    act(() => {
+      createdMediaElements.forEach((element) =>
+        element.onloadedmetadata?.(new Event('loadedmetadata')),
+      );
+    });
+
+    await waitFor(() => {
+      expect(uploadEditorMediaAssetFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ name: '胜利音效.mp3' }),
+        'audio',
+      );
+      expect(uploadEditorMediaAssetFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ name: '开场动画.mp4' }),
+        'video',
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: '添加胜利音效.mp3' })).toBeTruthy();
+      expect(screen.getByRole('button', { name: '添加开场动画.mp4' })).toBeTruthy();
+    });
+    expect(createEditorAssetMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        label: '胜利音效.mp3',
+        imageSrc:
+          '/generated-character-drafts/editor/asset-library/audio/胜利音效.mp3',
+        objectKey:
+          'generated-character-drafts/editor/asset-library/audio/胜利音效.mp3',
+        assetObjectId: 'assetobj-editor-audio',
+      }),
+    );
+    expect(createEditorAssetMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        label: '开场动画.mp4',
+        imageSrc:
+          '/generated-character-drafts/editor/asset-library/video/开场动画.mp4',
+        objectKey:
+          'generated-character-drafts/editor/asset-library/video/开场动画.mp4',
+        assetObjectId: 'assetobj-editor-video',
+      }),
+    );
+  });
+
+  it('opens login before uploading assets while logged out and resumes after login', async () => {
+    const openLoginModal = vi.fn();
+    const authValue = createAuthValue({ openLoginModal });
+
+    const { rerender } = render(
+      <AuthUiContext.Provider value={authValue}>
+        <ImageCanvasEditorView />
+      </AuthUiContext.Provider>,
+    );
+
+    await userEvent.upload(screen.getByLabelText('上传媒体文件'), [
+      new File(['image'], '登录后上传.png', { type: 'image/png' }),
+    ]);
+
+    expect(openLoginModal).toHaveBeenCalled();
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(
+      screen.queryByRole('button', { name: '上传失败登录后上传.png' }),
+    ).toBeNull();
+
+    const resumeUpload =
+      openLoginModal.mock.calls[openLoginModal.mock.calls.length - 1]?.[0];
+    expect(typeof resumeUpload).toBe('function');
+    rerender(
+      <AuthUiContext.Provider
+        value={createAuthValue({
+          user: {
+            id: 'user-1',
+            publicUserCode: 'U001',
+            displayName: '测试用户',
+            avatarUrl: null,
+            phoneNumberMasked: '138****0000',
+            loginMethod: 'password',
+            bindingStatus: 'active',
+            wechatBound: false,
+          },
+          canAccessProtectedData: true,
+          openLoginModal,
+        })}
+      >
+        <ImageCanvasEditorView />
+      </AuthUiContext.Provider>,
+    );
+    act(() => {
+      (resumeUpload as () => void)();
+    });
+
+    await waitFor(() => {
+      expect(createEditorAssetMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('shows an uploading placeholder card before restoring the normal asset card', async () => {
+    const deferredAsset = createDeferred<{
+      assetId: string;
+      folderId: string;
+      label: string;
+      imageSrc: string;
+      width: number;
+      height: number;
+      sourceType: 'uploaded';
+    }>();
+    createEditorAssetMock.mockReturnValueOnce(deferredAsset.promise);
+    render(<ImageCanvasEditorView />);
+
+    await userEvent.upload(screen.getByLabelText('上传媒体文件'), [
+      new File(['image'], '素材上传进度.png', { type: 'image/png' }),
+    ]);
+
+    expect(
+      await screen.findByLabelText('素材素材上传进度.png上传进度'),
+    ).toBeTruthy();
+    expect(
+      screen.getByRole('button', { name: '上传中素材上传进度.png' }),
+    ).toBeTruthy();
+
+    deferredAsset.resolve({
+      assetId: 'asset-upload-progress',
+      folderId: 'project',
+      label: '素材上传进度.png',
+      imageSrc: 'data:image/png;base64,cHJvZ3Jlc3M=',
+      width: 420,
+      height: 315,
+      sourceType: 'uploaded',
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: '添加素材上传进度.png' }),
+      ).toBeTruthy();
+    });
+    expect(screen.queryByLabelText('素材素材上传进度.png上传进度')).toBeNull();
+  });
+
+  it('opens login when asset creation returns unauthorized during upload', async () => {
+    const openLoginModal = vi.fn();
+    createEditorAssetMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+
+    render(
+      <AuthUiContext.Provider
+        value={createAuthValue({
+          user: {
+            id: 'user-1',
+            publicUserCode: 'U001',
+            displayName: '测试用户',
+            avatarUrl: null,
+            phoneNumberMasked: '138****0000',
+            loginMethod: 'password',
+            bindingStatus: 'active',
+            wechatBound: false,
+          },
+          canAccessProtectedData: true,
+          openLoginModal,
+        })}
+      >
+        <ImageCanvasEditorView />
+      </AuthUiContext.Provider>,
+    );
+
+    await userEvent.upload(screen.getByLabelText('上传媒体文件'), [
+      new File(['image'], '过期登录.png', { type: 'image/png' }),
+    ]);
+
+    await waitFor(() => {
+      expect(openLoginModal).toHaveBeenCalledTimes(1);
+    });
+    expect(screen.getByText('请先登录')).toBeTruthy();
+  });
+
+  it('supports asset selection mode and batch delete with shared toolbar', async () => {
+    const user = userEvent.setup();
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-a',
+          folderId: 'project',
+          label: '账号素材A',
+          imageSrc: 'data:image/png;base64,YQ==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+        {
+          assetId: 'asset-b',
+          folderId: 'project',
+          label: '账号素材B',
+          imageSrc: 'data:image/png;base64,Yg==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByRole('button', { name: '添加账号素材A' });
+    await user.click(screen.getByRole('button', { name: '素材选择模式' }));
+    await user.click(screen.getByRole('button', { name: '选择素材账号素材A' }));
+
+    const batchToolbar = screen.getByRole('toolbar', { name: '素材批量操作' });
+    expect(within(batchToolbar).getByText(/已选 1/u)).toBeTruthy();
+    await user.click(
+      within(batchToolbar).getByRole('button', { name: '删除' }),
+    );
+
+    expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-a');
+    expect(
+      screen.queryByRole('button', { name: '选择素材账号素材A' }),
+    ).toBeNull();
+  });
+
+  it('removes canvas layers linked to deleted assets', async () => {
+    const user = userEvent.setup();
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-a',
+          folderId: 'project',
+          label: '账号素材A',
+          imageSrc: 'data:image/png;base64,YQ==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+        {
+          assetId: 'asset-b',
+          folderId: 'project',
+          label: '账号素材B',
+          imageSrc: 'data:image/png;base64,Yg==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    await user.click(
+      await screen.findByRole('button', { name: '添加账号素材A' }),
+    );
+    await user.click(screen.getByRole('button', { name: '添加账号素材B' }));
+    expect(screen.getByAltText('画布图片：账号素材A')).toBeTruthy();
+    expect(screen.getByAltText('画布图片：账号素材B')).toBeTruthy();
+
+    await user.click(screen.getByRole('button', { name: '素材选择模式' }));
+    await user.click(
+      within(screen.getByRole('toolbar', { name: '素材批量操作' })).getByRole(
+        'button',
+        { name: '全选' },
+      ),
+    );
+    await waitFor(() => {
+      expect(
+        within(screen.getByRole('toolbar', { name: '素材批量操作' })).getByText(
+          /已选 2/u,
+        ),
+      ).toBeTruthy();
+    });
+    await user.click(
+      within(screen.getByRole('toolbar', { name: '素材批量操作' })).getByRole(
+        'button',
+        { name: '删除' },
+      ),
+    );
+
+    await waitFor(() => {
+      expect(screen.queryByAltText('画布图片：账号素材A')).toBeNull();
+      expect(screen.queryByAltText('画布图片：账号素材B')).toBeNull();
+    });
+    expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-a');
+    expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-b');
+  });
+
+  it('saves a library asset layer right after creating its canvas resource', async () => {
+    const user = userEvent.setup();
+    createEditorProjectResourceMock.mockResolvedValueOnce({
+      resourceId: 'resource-added-asset-a',
+      projectId: 'editor-project-default',
+      imageSrc: 'data:image/png;base64,YQ==',
+      width: 320,
+      height: 240,
+      sourceType: 'uploaded',
+    });
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '空画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-a',
+          folderId: 'project',
+          label: '账号素材A',
+          imageSrc: 'data:image/png;base64,YQ==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    await user.click(
+      await screen.findByRole('button', { name: '添加账号素材A' }),
+    );
+
+    expect(await screen.findByAltText('画布图片：账号素材A')).toBeTruthy();
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: '账号素材A',
+              resourceId: 'resource-added-asset-a',
+              sourceAssetId: 'asset-a',
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('selects multiple assets with a marquee in asset selection mode', async () => {
+    const user = userEvent.setup();
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-a',
+          folderId: 'project',
+          label: '账号素材A',
+          imageSrc: 'data:image/png;base64,YQ==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+        {
+          assetId: 'asset-b',
+          folderId: 'project',
+          label: '账号素材B',
+          imageSrc: 'data:image/png;base64,Yg==',
+          width: 320,
+          height: 240,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    const firstAssetButton = await screen.findByRole('button', {
+      name: '添加账号素材A',
+    });
+    const secondAssetButton = screen.getByRole('button', {
+      name: '添加账号素材B',
+    });
+    const assetList = firstAssetButton.closest(
+      '.image-canvas-editor__asset-list',
+    ) as HTMLElement;
+    vi.spyOn(assetList, 'getBoundingClientRect').mockReturnValue({
+      x: 0,
+      y: 0,
+      left: 0,
+      top: 0,
+      right: 320,
+      bottom: 600,
+      width: 320,
+      height: 600,
+      toJSON: () => ({}),
+    });
+    vi.spyOn(
+      firstAssetButton.closest('[data-asset-id]') as HTMLElement,
+      'getBoundingClientRect',
+    ).mockReturnValue({
+      x: 16,
+      y: 120,
+      left: 16,
+      top: 120,
+      right: 280,
+      bottom: 200,
+      width: 264,
+      height: 80,
+      toJSON: () => ({}),
+    });
+    vi.spyOn(
+      secondAssetButton.closest('[data-asset-id]') as HTMLElement,
+      'getBoundingClientRect',
+    ).mockReturnValue({
+      x: 16,
+      y: 240,
+      left: 16,
+      top: 240,
+      right: 280,
+      bottom: 320,
+      width: 264,
+      height: 80,
+      toJSON: () => ({}),
+    });
+
+    await user.click(screen.getByRole('button', { name: '素材选择模式' }));
+    dispatchPointerEvent(assetList, 'pointerdown', {
+      button: 0,
+      pointerId: 88,
+      clientX: 8,
+      clientY: 100,
+    });
+    dispatchPointerEvent(assetList, 'pointermove', {
+      button: 0,
+      pointerId: 88,
+      clientX: 300,
+      clientY: 330,
+    });
+    dispatchPointerEvent(assetList, 'pointerup', {
+      button: 0,
+      pointerId: 88,
+      clientX: 300,
+      clientY: 330,
+    });
+
+    const batchToolbar = screen.getByRole('toolbar', { name: '素材批量操作' });
+    expect(within(batchToolbar).getByText(/已选 2/u)).toBeTruthy();
+  });
+
+
+  it('drops an image file on the canvas as a new canvas layer', async () => {
+    render(<ImageCanvasEditorView />);
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    const viewport = screen.getByLabelText('画布工作区');
+    fireEvent.drop(viewport, {
+      clientX: 430,
+      clientY: 260,
+      dataTransfer: {
+        files: [new File(['image'], '测试上传.png', { type: 'image/png' })],
+        types: ['Files'],
+      },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：测试上传.png')).toBeTruthy();
+    });
+    expect(createEditorAssetMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        label: '测试上传.png',
+        imageSrc: expect.stringMatching(/^data:image\/png;base64,/u),
+      }),
+    );
+    expect(screen.getByRole('heading', { name: '素材' })).toBeTruthy();
+    expect(
+      screen.getByRole('button', { name: '打开素材' }).getAttribute(
+        'aria-pressed',
+      ),
+    ).toBe('true');
+    expect(
+      screen
+        .getByRole('button', { name: '选择测试上传.png' })
+        .className.includes('image-canvas-editor__layer--selected'),
+    ).toBe(true);
+  });
+
+  it('drops files into the asset panel only once without creating canvas layers', async () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.drop(screen.getByRole('region', { name: '项目素材' }), {
+      dataTransfer: {
+        files: [new File(['image'], '素材拖拽.png', { type: 'image/png' })],
+        types: ['Files'],
+      },
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: '添加素材拖拽.png' }),
+      ).toBeTruthy();
+    });
+    expect(createEditorAssetMock).toHaveBeenCalledTimes(1);
+    expect(screen.queryByAltText('画布图片：素材拖拽.png')).toBeNull();
+  });
+
+  it('adds an asset library image to the canvas by dragging it onto the viewport', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const sourceAsset = await screen.findByRole('button', {
+      name: '添加抓大鹅素材',
+    });
+    const sourceAssetRow = sourceAsset.closest(
+      '.image-canvas-editor__asset-row',
+    );
+    const viewport = screen.getByLabelText('画布工作区');
+    const dataTransfer = createDataTransferStub();
+
+    if (!sourceAssetRow) {
+      throw new Error('asset row should exist');
+    }
+    fireEvent.dragStart(sourceAssetRow, { dataTransfer });
+    fireEvent.dragOver(viewport, {
+      clientX: 520,
+      clientY: 300,
+      dataTransfer,
+    });
+
+    await waitFor(() => {
+      expect(screen.getByText('添加到画布')).toBeTruthy();
+    });
+
+    fireEvent.drop(viewport, {
+      clientX: 520,
+      clientY: 300,
+      dataTransfer,
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText('添加到画布')).toBeNull();
+    });
+    expect(screen.getByAltText('画布图片：抓大鹅素材')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '选择抓大鹅素材' })).toBeTruthy();
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'editor-project-default',
+      expect.objectContaining({
+        imageSrc: '/creation-type-references/match3d.webp',
+        sourceType: 'uploaded',
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+  });
+
+});
diff --git a/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
new file mode 100644
index 000000000..fd15863af
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx
@@ -0,0 +1,3300 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ApiClientError,
+  dispatchPointerEvent,
+  ImageCanvasEditorView,
+  setupImageCanvasEditorViewTestLifecycle,
+} from './ImageCanvasEditorView.test-utils';
+
+const generateEditorImageMock = vi.hoisted(() => vi.fn());
+const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
+const extractEditorUiDesignAssetsMock = vi.hoisted(() => vi.fn());
+const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
+const editEditorImageMock = vi.hoisted(() => vi.fn());
+const createEditorAssetMock = vi.hoisted(() => vi.fn());
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const createEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetMock = vi.hoisted(() => vi.fn());
+const loadEditorAssetLibraryMock = vi.hoisted(() => vi.fn());
+const loadEditorProjectMock = vi.hoisted(() => vi.fn());
+const loadOrCreateRecentEditorProjectMock = vi.hoisted(() => vi.fn());
+const renameEditorProjectMock = vi.hoisted(() => vi.fn());
+const saveEditorProjectLayoutMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: editEditorImageMock,
+    extractEditorUiDesignAssets: extractEditorUiDesignAssetsMock,
+    createEditorAsset: createEditorAssetMock,
+    createEditorAssetFolder: createEditorAssetFolderMock,
+    createEditorProjectResource: createEditorProjectResourceMock,
+    deleteEditorAsset: deleteEditorAssetMock,
+    deleteEditorAssetFolder: deleteEditorAssetFolderMock,
+    generateEditorCharacterAnimation: generateEditorCharacterAnimationMock,
+    generateEditorIconSpritesheet: generateEditorIconSpritesheetMock,
+    generateEditorImage: generateEditorImageMock,
+    loadEditorAssetLibrary: loadEditorAssetLibraryMock,
+    loadEditorProject: loadEditorProjectMock,
+    loadOrCreateRecentEditorProject: loadOrCreateRecentEditorProjectMock,
+    renameEditorProject: renameEditorProjectMock,
+    saveEditorProjectLayout: saveEditorProjectLayoutMock,
+    updateEditorAsset: updateEditorAssetMock,
+    updateEditorAssetFolder: updateEditorAssetFolderMock,
+  };
+});
+
+describe('ImageCanvasEditorView generation integration', () => {
+  setupImageCanvasEditorViewTestLifecycle({
+    generateEditorImageMock,
+    generateEditorIconSpritesheetMock,
+    extractEditorUiDesignAssetsMock,
+    generateEditorCharacterAnimationMock,
+    editEditorImageMock,
+    createEditorAssetMock,
+    createEditorProjectResourceMock,
+    createEditorAssetFolderMock,
+    updateEditorAssetMock,
+    updateEditorAssetFolderMock,
+    deleteEditorAssetFolderMock,
+    deleteEditorAssetMock,
+    loadEditorAssetLibraryMock,
+    loadEditorProjectMock,
+    loadOrCreateRecentEditorProjectMock,
+    renameEditorProjectMock,
+    saveEditorProjectLayoutMock,
+  });
+
+  const openGenerationDimensionsPanel = (
+    panel: HTMLElement,
+    labelPrefix = '生成图片',
+  ) => {
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: new RegExp(`^${labelPrefix}尺寸 `, 'u'),
+      }),
+    );
+    return screen.getByRole('menu', { name: `${labelPrefix}尺寸选项` });
+  };
+
+  const openGenerationModelPanel = (
+    panel: HTMLElement,
+    labelPrefix = '生成图片',
+  ) => {
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: new RegExp(`^${labelPrefix}模型 `, 'u'),
+      }),
+    );
+    return screen.getByRole('menu', { name: `${labelPrefix}模型选项` });
+  };
+
+  const selectGenerationModel = (panel: HTMLElement, modelLabel: string) => {
+    const modelPanel = openGenerationModelPanel(panel);
+    fireEvent.click(
+      within(modelPanel).getByRole('button', {
+        name: new RegExp(`^${modelLabel}(?: ✓)?$`, 'u'),
+      }),
+    );
+  };
+
+  const selectGenerationDimensions = (
+    panel: HTMLElement,
+    aspectRatio: string,
+    imageSize: string,
+  ) => {
+    const dimensionsPanel = openGenerationDimensionsPanel(panel);
+    fireEvent.click(
+      within(dimensionsPanel).getByRole('button', {
+        name: new RegExp(`^(?:比例 )?${aspectRatio}$`, 'u'),
+      }),
+    );
+    fireEvent.click(
+      within(dimensionsPanel).getByRole('button', {
+        name: new RegExp(`^(?:尺寸 )?${imageSize}$`, 'u'),
+      }),
+    );
+  };
+
+  const createGeneratedResource = ({
+    resourceId,
+    projectId = 'editor-project-default',
+    imageSrc = 'data:image/png;base64,generated',
+    width = 1024,
+    height = 1024,
+    objectKey,
+    assetObjectId,
+    assetKind,
+    generationInputs,
+  }: {
+    resourceId: string;
+    projectId?: string;
+    imageSrc?: string;
+    width?: number;
+    height?: number;
+    objectKey?: string;
+    assetObjectId?: string;
+    assetKind?: string;
+    generationInputs?: unknown;
+  }) => ({
+    resourceId,
+    projectId,
+    imageSrc,
+    objectKey,
+    assetObjectId,
+    width,
+    height,
+    sourceType: 'generated',
+    assetKind,
+    generationInputs,
+    createdAt: '2026-06-19T00:00:00.000Z',
+    updatedAt: '2026-06-19T00:00:00.000Z',
+  });
+
+  const createGeneratedAsset = ({
+    assetId,
+    folderId = 'folder-project',
+    label = '生成素材',
+    imageSrc = 'data:image/png;base64,generated',
+    width = 1024,
+    height = 1024,
+    objectKey,
+    assetObjectId,
+    assetKind,
+    generationInputs,
+  }: {
+    assetId: string;
+    folderId?: string;
+    label?: string;
+    imageSrc?: string;
+    width?: number;
+    height?: number;
+    objectKey?: string;
+    assetObjectId?: string;
+    assetKind?: string;
+    generationInputs?: unknown;
+  }) => ({
+    assetId,
+    folderId,
+    label,
+    imageSrc,
+    objectKey,
+    assetObjectId,
+    width,
+    height,
+    sourceType: 'generated',
+    assetKind,
+    generationInputs,
+    createdAt: '2026-06-19T00:00:00.000Z',
+    updatedAt: '2026-06-19T00:00:00.000Z',
+  });
+
+  it('restores generated image composer from saved generator snapshots', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-generated-dialog',
+      title: '已生成画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-generated-restored',
+          resourceId: 'resource-generated-restored',
+          title: '生成图片 1',
+          x: 236,
+          y: 66,
+          width: 512,
+          height: 512,
+          originalWidth: 512,
+          originalHeight: 512,
+          zIndex: 11,
+          sourceType: 'generated',
+          generationInputs: {
+            fields: [{ title: '生成提示词', value: '刷新后恢复生成器' }],
+            references: [],
+          },
+        },
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-1',
+          resourceId: 'generation-dialog:generation-dialog-1',
+          dialog: {
+            id: 'generation-dialog-1',
+            mode: 'generate',
+            prompt: '刷新后恢复生成器',
+            status: 'idle',
+            composerOpen: true,
+            generatedLayerId: 'layer-generated-restored',
+            placeholder: {
+              x: 282,
+              y: 112,
+              width: 420,
+              height: 420,
+              originalWidth: 2048,
+              originalHeight: 2048,
+            },
+          },
+        },
+      ],
+      resources: [
+        {
+          resourceId: 'resource-generated-restored',
+          projectId: 'editor-project-generated-dialog',
+          imageSrc: 'data:image/png;base64,cmVzdG9yZWQ=',
+          width: 512,
+          height: 512,
+          sourceType: 'generated',
+        },
+      ],
+      updatedAt: '2026-06-17T00:00:00.000Z',
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    expect(await screen.findByAltText('画布图片：生成图片 1')).toBeTruthy();
+    expect(screen.queryByLabelText('图像生成占位图')).toBeNull();
+    const generateDialog = screen.getByRole('dialog', { name: '生成图片' });
+    expect(generateDialog).toBeTruthy();
+    expect((screen.getByLabelText('生成提示词') as HTMLTextAreaElement).value).toBe(
+      '刷新后恢复生成器',
+    );
+  });
+
+  it('restores publication material composer fields and references from saved generator snapshots', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-publication-dialog',
+      title: '宣发画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-publication',
+          resourceId: 'generation-dialog:generation-dialog-publication',
+          dialog: {
+            id: 'generation-dialog-publication',
+            mode: 'publication',
+            prompt: '马戏团午夜惊魂｜非对称对抗｜找到钥匙逃离',
+            status: 'idle',
+            composerOpen: true,
+            publicationWorkflowId: 'publication-promo-poster',
+            publicationGameInfo: {
+              gameName: '马戏团午夜惊魂',
+              gameCategories: '非对称对抗',
+              gameDescription: '找到钥匙，开门逃离马戏团',
+            },
+            publicationReferences: [
+              {
+                id: 'publication-reference-1',
+                label: '首图参考',
+                src: '/generated-character-drafts/editor/reference.png',
+                objectKey: 'generated-character-drafts/editor/reference.png',
+                assetObjectId: 'asset-object-publication-reference',
+              },
+            ],
+            imageModel: 'gpt-image-2',
+            aspectRatio: '16:9',
+            imageSize: '2K',
+            placeholder: {
+              x: 282,
+              y: 112,
+              width: 1280,
+              height: 720,
+              originalWidth: 1280,
+              originalHeight: 720,
+            },
+          },
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-17T00:00:00.000Z',
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    const publicationDialog = await screen.findByRole('dialog', {
+      name: '运营海报生成卡片',
+    });
+    expect(
+      (within(publicationDialog).getByRole('textbox', {
+        name: '运营海报游戏名',
+      }) as HTMLInputElement).value,
+    ).toBe('马戏团午夜惊魂');
+    expect(
+      (within(publicationDialog).getByRole('textbox', {
+        name: '运营海报游戏分类',
+      }) as HTMLInputElement).value,
+    ).toBe('非对称对抗');
+    expect(
+      (within(publicationDialog).getByRole('textbox', {
+        name: '运营海报一句话描述游戏',
+      }) as HTMLTextAreaElement).value,
+    ).toBe('找到钥匙，开门逃离马戏团');
+    expect(within(publicationDialog).getByLabelText('首图参考')).toBeTruthy();
+    expect(screen.getByLabelText('宣发素材生成占位图')).toBeTruthy();
+  });
+
+  it('opens a canvas generation frame and composer before creating a generated layer', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,ZmFrZS1pbWFnZQ==',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '一张明亮的拼图主视觉',
+      actualPrompt: '一张明亮的拼图主视觉',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-real-task-1',
+      resource: createGeneratedResource({
+        resourceId: 'resource-generated-image-1',
+        imageSrc: 'data:image/png;base64,ZmFrZS1pbWFnZQ==',
+        assetKind: 'character',
+      }),
+      asset: createGeneratedAsset({
+        assetId: 'asset-generated-image-1',
+        label: '生成图片 1',
+        imageSrc: 'data:image/png;base64,ZmFrZS1pbWFnZQ==',
+        assetKind: 'character',
+      }),
+    });
+    render(<ImageCanvasEditorView />);
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    fireEvent.click(
+      within(bottomToolbar).getByRole('button', { name: '生成图片' }),
+    );
+
+    const generateDialog = screen.getByRole('dialog', { name: '生成图片' });
+    const initialComposerTop = Number.parseFloat(
+      (generateDialog as HTMLElement).style.top,
+    );
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+    expect(within(generateDialog).getByText('参考图')).toBeTruthy();
+    expect(
+      within(generateDialog).getByRole('button', { name: '添加参考图' })
+        .className,
+    ).toContain('image-canvas-editor__reference-chip');
+    expect(
+      within(generateDialog).getByRole('button', { name: '添加参考图' })
+        .className,
+    ).toContain('image-canvas-editor__reference-chip');
+    const generatePrompt = screen.getByLabelText('生成提示词');
+    expect(generatePrompt.className).toContain('platform-text-field');
+    expect(generatePrompt.className).toContain(
+      'image-canvas-editor__generation-prompt',
+    );
+    expect(
+      within(generateDialog).getByRole('button', {
+        name: '生成图片尺寸 1:1·1K',
+      }).className,
+    ).toContain('platform-inline-option-button');
+    expect(
+      within(generateDialog).getByRole('button', {
+        name: '生成图片模型 nanobanana2',
+      }).className,
+    ).toContain('platform-inline-option-button');
+    expect(
+      within(generateDialog).getByRole('button', { name: '生成' }).className,
+    ).toContain('platform-button');
+    expect(
+      within(generateDialog).getByRole('button', { name: '生成' }).className,
+    ).toContain('image-canvas-editor__generation-submit');
+    expect(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).toBeTruthy();
+
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '一张明亮的拼图主视觉' },
+    });
+    fireEvent.click(
+      within(generateDialog).getByRole('button', { name: '生成' }),
+    );
+
+    expect(screen.getByRole('status').textContent).toContain('生成中');
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        prompt: '一张明亮的拼图主视觉',
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetLabel: expect.stringMatching(/生成图片/u),
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
+    });
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(createEditorProjectResourceMock).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole('button', { name: '打开素材' }));
+    expect(
+      screen.getByRole('button', { name: /添加生成图片/u }),
+    ).toBeTruthy();
+    const generatedLayer = screen
+      .getByAltText(/画布图片：生成图片/)
+      .closest('button')!;
+    const anchoredGenerateDialog = screen.getByRole('dialog', {
+      name: '生成图片',
+    });
+    expect(anchoredGenerateDialog).toBeTruthy();
+    expect(
+      Number.parseFloat((anchoredGenerateDialog as HTMLElement).style.top),
+    ).toBeGreaterThan(
+      Number.parseFloat((generatedLayer as HTMLElement).style.top),
+    );
+    expect(
+      Number.parseFloat((generatedLayer as HTMLElement).style.top),
+    ).toBeLessThan(initialComposerTop);
+    expect(screen.queryByLabelText('图像生成占位图')).toBeNull();
+    const metadataButtons = screen.getAllByRole('button', {
+      name: /查看生成图片 .*图片信息/,
+    });
+    expect(metadataButtons[0]).toBeTruthy();
+    fireEvent.click(metadataButtons[0]!);
+
+    const infoPanel = screen.getByRole('dialog', { name: '图片信息' });
+    expect(within(infoPanel).queryByText('Prompt')).toBeNull();
+    expect(
+      within(infoPanel).queryByRole('button', { name: '复制Prompt' }),
+    ).toBeNull();
+    expect(within(infoPanel).getByText('生成输入')).toBeTruthy();
+    expect(within(infoPanel).getByText('生成提示词')).toBeTruthy();
+    expect(within(infoPanel).getByText('一张明亮的拼图主视觉')).toBeTruthy();
+  });
+
+  it('drags the generation placeholder and places the generated layer there', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,ZHJhZ2dlZC1mcmFtZQ==',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '拖拽后的生成图',
+      actualPrompt: '拖拽后的生成图',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-drag-frame-1',
+    });
+    render(<ImageCanvasEditorView />);
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    const initialComposerTop = Number.parseFloat(
+      (screen.getByRole('dialog', { name: '生成图片' }) as HTMLElement).style
+        .top,
+    );
+    const frame = screen.getByLabelText('图像生成占位图');
+    dispatchPointerEvent(frame, 'pointerdown', {
+      button: 0,
+      pointerId: 61,
+      clientX: 500,
+      clientY: 260,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      pointerId: 61,
+      clientX: 582,
+      clientY: 342,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointerup', {
+      pointerId: 61,
+      clientX: 582,
+      clientY: 342,
+    });
+    const draggedComposerTop = Number.parseFloat(
+      (screen.getByRole('dialog', { name: '生成图片' }) as HTMLElement).style
+        .top,
+    );
+    expect(draggedComposerTop).toBeGreaterThan(initialComposerTop);
+    const draggedFrame = screen.getByLabelText('图像生成占位图') as HTMLElement;
+    const draggedFrameCenterX =
+      Number.parseFloat(draggedFrame.style.left) +
+      Number.parseFloat(draggedFrame.style.width) / 2;
+    const draggedFrameCenterY =
+      Number.parseFloat(draggedFrame.style.top) +
+      Number.parseFloat(draggedFrame.style.height) / 2;
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '拖拽后的生成图' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
+    });
+
+    const generatedLayer = screen
+      .getByAltText(/画布图片：生成图片/)
+      .closest('button')!;
+    const anchoredGenerateDialog = screen.getByRole('dialog', {
+      name: '生成图片',
+    });
+    expect(anchoredGenerateDialog).toBeTruthy();
+    expect(
+      Number.parseFloat((anchoredGenerateDialog as HTMLElement).style.top),
+    ).toBeGreaterThan(
+      Number.parseFloat((generatedLayer as HTMLElement).style.top),
+    );
+    expect(screen.queryByLabelText('图像生成占位图')).toBeNull();
+    expect(
+      Number.parseFloat((generatedLayer as HTMLElement).style.left) +
+        Number.parseFloat((generatedLayer as HTMLElement).style.width) / 2,
+    ).toBeCloseTo(draggedFrameCenterX, 1);
+    expect(
+      Number.parseFloat((generatedLayer as HTMLElement).style.top) +
+        Number.parseFloat((generatedLayer as HTMLElement).style.height) / 2,
+    ).toBeCloseTo(draggedFrameCenterY, 1);
+  });
+
+  it('keeps the generation placeholder draggable while the image is generating', async () => {
+    let resolveGeneration!: (value: unknown) => void;
+    generateEditorImageMock.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveGeneration = resolve;
+      }),
+    );
+    render(<ImageCanvasEditorView />);
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '生成中继续拖动的图片' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    const frame = screen.getByLabelText('图像生成占位图');
+    expect(frame.className).toContain(
+      'image-canvas-editor__generation-frame--generating',
+    );
+    const initialLeft = Number.parseFloat((frame as HTMLElement).style.left);
+    const initialTop = Number.parseFloat((frame as HTMLElement).style.top);
+
+    dispatchPointerEvent(frame, 'pointerdown', {
+      button: 0,
+      pointerId: 67,
+      clientX: 500,
+      clientY: 260,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      pointerId: 67,
+      clientX: 620,
+      clientY: 360,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointerup', {
+      pointerId: 67,
+      clientX: 620,
+      clientY: 360,
+    });
+
+    const draggedFrame = screen.getByLabelText('图像生成占位图');
+    expect(
+      Number.parseFloat((draggedFrame as HTMLElement).style.left),
+    ).toBeGreaterThan(initialLeft);
+    expect(
+      Number.parseFloat((draggedFrame as HTMLElement).style.top),
+    ).toBeGreaterThan(initialTop);
+
+    await act(async () => {
+      resolveGeneration({
+        imageSrc: 'data:image/png;base64,Z2VuZXJhdGluZy1kcmFn',
+        width: 1024,
+        height: 1024,
+        sourceType: 'generated',
+        prompt: '生成中继续拖动的图片',
+        actualPrompt: '生成中继续拖动的图片',
+        model: 'gpt-image-2',
+        provider: 'VectorEngine',
+        taskId: 'editor-generating-drag-1',
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
+    });
+    const generatedLayer = screen
+      .getByAltText(/画布图片：生成图片/)
+      .closest('button')!;
+    expect(
+      Number.parseFloat((generatedLayer as HTMLElement).style.left) +
+        Number.parseFloat((generatedLayer as HTMLElement).style.width) / 2,
+    ).toBeCloseTo(
+      Number.parseFloat((draggedFrame as HTMLElement).style.left) +
+        Number.parseFloat((draggedFrame as HTMLElement).style.width) / 2,
+      1,
+    );
+    expect(
+      Number.parseFloat((generatedLayer as HTMLElement).style.top) +
+        Number.parseFloat((generatedLayer as HTMLElement).style.height) / 2,
+    ).toBeCloseTo(
+      Number.parseFloat((draggedFrame as HTMLElement).style.top) +
+        Number.parseFloat((draggedFrame as HTMLElement).style.height) / 2,
+      1,
+    );
+  });
+
+  it('confirms before deleting a generating placeholder because mud points are not refunded', async () => {
+    let resolveGeneration!: (value: unknown) => void;
+    generateEditorImageMock.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveGeneration = resolve;
+      }),
+    );
+    render(<ImageCanvasEditorView />);
+
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '准备删除的生成中图片' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    const frame = screen.getByLabelText('图像生成占位图');
+    expect(frame.className).toContain(
+      'image-canvas-editor__generation-frame--generating',
+    );
+
+    fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
+
+    const confirmDialog = screen.getByRole('dialog', {
+      name: '删除生成中的占位图',
+    });
+    expect(
+      within(confirmDialog).getByText(
+        '删除后会停止在画布中显示这个生成任务，已消耗的泥点不会返还。',
+      ),
+    ).toBeTruthy();
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+
+    fireEvent.click(within(confirmDialog).getByRole('button', { name: '取消' }));
+    expect(screen.queryByRole('dialog', { name: '删除生成中的占位图' })).toBeNull();
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
+    fireEvent.click(screen.getByRole('button', { name: '确认删除' }));
+
+    expect(screen.queryByLabelText('图像生成占位图')).toBeNull();
+
+    await act(async () => {
+      resolveGeneration({
+        imageSrc: 'data:image/png;base64,ZGVsZXRlZC1wbGFjZWhvbGRlcg==',
+        width: 1024,
+        height: 1024,
+        sourceType: 'generated',
+        prompt: '准备删除的生成中图片',
+        actualPrompt: '准备删除的生成中图片',
+        model: 'gpt-image-2',
+        provider: 'VectorEngine',
+        taskId: 'editor-deleted-placeholder-1',
+      });
+    });
+
+    expect(screen.queryByAltText(/画布图片：生成图片/)).toBeNull();
+  });
+
+  it('hides the generation composer when selecting another image but keeps the placeholder', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 62,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+
+    expect(screen.queryByRole('dialog', { name: '生成图片' })).toBeNull();
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+
+    fireEvent.pointerDown(screen.getByLabelText('图像生成占位图'), {
+      button: 0,
+      pointerId: 64,
+      clientX: 300,
+      clientY: 180,
+    });
+
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+  });
+
+  it('hides the generation composer when clicking the canvas outside generation controls', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+
+    fireEvent.pointerDown(screen.getByLabelText('画布工作区'), {
+      button: 0,
+      pointerId: 63,
+      clientX: 260,
+      clientY: 180,
+    });
+
+    expect(screen.queryByRole('dialog', { name: '生成图片' })).toBeNull();
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+  });
+
+  it('hides quick edit and redraw panels when clicking the canvas outside generation controls', () => {
+    render(<ImageCanvasEditorView />);
+    const viewport = screen.getByLabelText('画布工作区');
+    const sourceLayer = screen.getByAltText('画布图片：拼图素材').closest('button')!;
+
+    fireEvent.pointerDown(sourceLayer, {
+      button: 0,
+      pointerId: 631,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.pointerUp(viewport, {
+      pointerId: 631,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑' }));
+    expect(screen.getByRole('dialog', { name: '快速编辑图片' })).toBeTruthy();
+    expect(
+      screen.queryByRole('button', { name: '关闭快速编辑图片' }),
+    ).toBeNull();
+
+    fireEvent.pointerDown(viewport, {
+      button: 0,
+      pointerId: 632,
+      clientX: 260,
+      clientY: 180,
+    });
+
+    expect(
+      screen.queryByRole('dialog', { name: '快速编辑图片' }),
+    ).toBeNull();
+
+    fireEvent.pointerDown(sourceLayer, {
+      button: 0,
+      pointerId: 633,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.pointerUp(viewport, {
+      pointerId: 633,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '改造' }));
+    expect(screen.getByRole('dialog', { name: '重绘图片' })).toBeTruthy();
+    expect(
+      screen.queryByRole('button', { name: '关闭重绘图片' }),
+    ).toBeNull();
+
+    fireEvent.pointerDown(viewport, {
+      button: 0,
+      pointerId: 634,
+      clientX: 280,
+      clientY: 190,
+    });
+
+    expect(screen.queryByRole('dialog', { name: '重绘图片' })).toBeNull();
+  });
+
+  it('does not render a standalone close button on the generation composer', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+
+    expect(
+      screen.queryByRole('button', { name: '关闭生成图片' }),
+    ).toBeNull();
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+  });
+
+  it('shows generation errors instead of falling back to mock images', async () => {
+    generateEditorImageMock.mockRejectedValueOnce(
+      new Error('VectorEngine 未配置'),
+    );
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '一张真实生成失败的图' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect(screen.getByRole('status').textContent).toContain('生成中');
+
+    await waitFor(() => {
+      expect(screen.getByRole('alert').textContent).toContain(
+        'VectorEngine 未配置',
+      );
+    });
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+    expect(screen.queryByAltText(/画布图片：生成图片/)).toBeNull();
+  });
+
+  it('asks the user to log in when real generation is unauthorized', async () => {
+    generateEditorImageMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问（requestId: web-login-required）',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '一张需要登录生成的图' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(screen.getByRole('alert').textContent).toBe(
+        '请先登录后再生成图片',
+      );
+    });
+    expect(screen.queryByText(/requestId/u)).toBeNull();
+  });
+
+  it('hides image generation setting panels after generation starts while keeping the preview frame visible', async () => {
+    const cases = [
+      {
+        open: () => {
+          fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+          fireEvent.change(screen.getByLabelText('生成提示词'), {
+            target: { value: '生成中的普通图片' },
+          });
+          fireEvent.click(screen.getByRole('button', { name: '生成' }));
+        },
+        dialogName: '生成图片',
+        frameLabel: '图像生成占位图',
+      },
+      {
+        open: () => {
+          fireEvent.click(
+            within(
+              screen.getByRole('toolbar', { name: 'AI画布工具栏' }),
+            ).getByRole('button', { name: '生成规范' }),
+          );
+          fireEvent.click(
+            within(
+              screen.getByRole('menu', { name: '生成规范类型' }),
+            ).getByRole('menuitem', { name: '自定义规范' }),
+          );
+          fireEvent.change(screen.getByLabelText('自定义规范提示词'), {
+            target: { value: '生成中的自定义规范图' },
+          });
+          fireEvent.click(
+            within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
+              'button',
+              { name: '提交生成规范' },
+            ),
+          );
+        },
+        dialogName: '生成规范',
+        frameLabel: '规范生成占位图',
+      },
+      {
+        open: () => {
+          fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+          fireEvent.change(screen.getByLabelText('角色设定'), {
+            target: { value: '生成中的角色形象' },
+          });
+          fireEvent.click(screen.getByRole('button', { name: '生成' }));
+        },
+        dialogName: '生成角色形象',
+        frameLabel: '角色生成占位图',
+      },
+    ] as const;
+
+    for (const testCase of cases) {
+      generateEditorImageMock.mockReturnValueOnce(new Promise(() => undefined));
+      const { unmount } = render(<ImageCanvasEditorView />);
+      await waitFor(() => {
+        expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+      });
+
+      testCase.open();
+
+      expect(
+        screen.queryByRole('dialog', { name: testCase.dialogName }),
+      ).toBeNull();
+      const frame = screen.getByLabelText(testCase.frameLabel);
+      expect(frame.className).toContain(
+        'image-canvas-editor__generation-frame--generating',
+      );
+      expect(within(frame).getByRole('status').textContent).toContain('生成中');
+
+      unmount();
+    }
+  });
+
+  it('hides the icon material panel after generation starts while keeping the icon preview frame visible', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-icons-generating',
+      title: '图标素材生成中画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-icon-spec-generating',
+          resourceId: 'resource-icon-spec-generating',
+          title: '清爽按钮图标规范',
+          src: 'data:image/png;base64,icon-spec-generating',
+          x: 80,
+          y: 80,
+          width: 160,
+          height: 160,
+          originalWidth: 512,
+          originalHeight: 512,
+          zIndex: 10,
+          sourceType: 'generated',
+          assetKind: 'icon-spec',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    generateEditorIconSpritesheetMock.mockReturnValueOnce(
+      new Promise(() => undefined),
+    );
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByAltText('画布图片：清爽按钮图标规范');
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    fireEvent.click(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    );
+    fireEvent.click(
+      within(screen.getByRole('menu', { name: '图标规范来源' })).getByRole(
+        'menuitem',
+        { name: '从画布中选择' },
+      ),
+    );
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：清爽按钮图标规范').closest('button')!,
+      {
+        button: 0,
+        pointerId: 1260,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    fireEvent.click(
+      within(screen.getByRole('dialog', { name: '生成图标素材' })).getByRole(
+        'button',
+        { name: '生成' },
+      ),
+    );
+
+    expect(screen.queryByRole('dialog', { name: '生成图标素材' })).toBeNull();
+    const frame = screen.getByLabelText('图标素材生成占位图');
+    expect(frame.className).toContain(
+      'image-canvas-editor__generation-frame--generating',
+    );
+    expect(within(frame).getByRole('status').textContent).toContain('生成中');
+  });
+
+  it('opens character spec generation form and creates a labeled spec layer', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,c3BlYy1yb2xl',
+      width: 2048,
+      height: 1152,
+      sourceType: 'generated',
+      prompt: '角色规范提示词',
+      actualPrompt: '角色规范提示词',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-spec-role-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    const generationToolLabels = within(bottomToolbar)
+      .getAllByRole('button')
+      .filter((button) => button.getAttribute('aria-label')?.startsWith('生成'))
+      .map((button) => button.getAttribute('aria-label'));
+    expect(generationToolLabels).toContain('生成图片');
+    expect(generationToolLabels).toContain('生成规范');
+    fireEvent.click(
+      within(bottomToolbar).getByRole('button', { name: '生成规范' }),
+    );
+
+    const specMenu = screen.getByRole('menu', { name: '生成规范类型' });
+    expect(
+      within(specMenu).getByRole('menuitem', { name: '角色规范' }),
+    ).toBeTruthy();
+    expect(
+      within(specMenu).getByRole('menuitem', { name: '图标规范' }),
+    ).toBeTruthy();
+    expect(
+      within(specMenu).getByRole('menuitem', { name: '自定义规范' }),
+    ).toBeTruthy();
+
+    fireEvent.click(
+      within(specMenu).getByRole('menuitem', { name: '角色规范' }),
+    );
+
+    const specDialog = screen.getByRole('dialog', { name: '生成规范' });
+    expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
+    expect(screen.getByText('2048 x 1152')).toBeTruthy();
+    expect((screen.getByLabelText('玩法设定') as HTMLInputElement).value).toBe(
+      '战棋类RPG玩法',
+    );
+    expect((screen.getByLabelText('美术风格') as HTMLInputElement).value).toBe(
+      '像素风',
+    );
+    expect((screen.getByLabelText('头身比') as HTMLSelectElement).value).toBe(
+      '3',
+    );
+    expect((screen.getByLabelText('角色视角') as HTMLInputElement).value).toBe(
+      '右向斜侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯右视图，也禁止生成正面立绘。',
+    );
+    expect(
+      within(specDialog).getByRole('button', { name: '提交生成规范' })
+        .textContent,
+    ).toContain('生成5泥点');
+
+    fireEvent.change(screen.getByLabelText('玩法设定'), {
+      target: { value: '平台跳跃玩法' },
+    });
+    fireEvent.change(screen.getByLabelText('美术风格'), {
+      target: { value: '低多边形卡通' },
+    });
+    fireEvent.change(screen.getByLabelText('头身比'), {
+      target: { value: '4' },
+    });
+    fireEvent.change(screen.getByLabelText('角色视角'), {
+      target: { value: '左向三分之二侧身站姿' },
+    });
+    fireEvent.click(
+      within(specDialog).getByRole('button', { name: '提交生成规范' }),
+    );
+
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'spec',
+        model: 'gpt-image-2',
+        size: '2048x1152',
+        aspectRatio: '16:9',
+        imageSize: '2K',
+        prompt: expect.stringContaining('玩法设计：平台跳跃玩法'),
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetKind: 'spec',
+        generationInputs: expect.objectContaining({
+          fields: expect.arrayContaining([
+            expect.objectContaining({
+              title: '玩法设定',
+              value: '平台跳跃玩法',
+            }),
+          ]),
+        }),
+      }),
+    );
+    const prompt = generateEditorImageMock.mock.calls[0]?.[0]?.prompt ?? '';
+    expect(prompt).toContain('生成2D 角色美术视觉规范设定图');
+    expect(prompt).toContain('美术风格：低多边形卡通');
+    expect(prompt).toContain('头身比：4');
+    expect(prompt).toContain('视角要求：左向三分之二侧身站姿');
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：角色规范/)).toBeTruthy();
+    });
+    expect(screen.getByText('规范')).toBeTruthy();
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: expect.stringMatching(/角色规范/u),
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('shows visible titles for character spec, icon spec, and icon spritesheet generation fields', async () => {
+    render(<ImageCanvasEditorView />);
+    await screen.findByAltText('画布图片：拼图素材');
+
+    fireEvent.click(
+      within(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).getByRole(
+        'button',
+        { name: '生成规范' },
+      ),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '角色规范' }));
+
+    const characterSpecDialog = screen.getByRole('dialog', {
+      name: '生成规范',
+    });
+    ['玩法设定', '美术风格', '头身比', '角色视角'].forEach((title) => {
+      expect(within(characterSpecDialog).getByText(title)).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+
+    const iconSpritesheetPanel = screen.getByRole('dialog', {
+      name: '生成图标素材',
+    });
+    expect(
+      within(iconSpritesheetPanel).getByRole('button', {
+        name: '图标规范',
+      }),
+    ).toBeTruthy();
+    expect(
+      within(iconSpritesheetPanel).getByRole('textbox', {
+        name: '素材描述',
+      }),
+    ).toBeTruthy();
+    expect(within(iconSpritesheetPanel).queryByText('素材描述 1')).toBeNull();
+    expect(within(iconSpritesheetPanel).queryByText('素材描述 6')).toBeNull();
+    expect(
+      within(iconSpritesheetPanel).getByRole('button', {
+        name: '生成图片模型 nanobanana2',
+      }),
+    ).toBeTruthy();
+
+    fireEvent.click(
+      within(iconSpritesheetPanel).getByRole('button', {
+        name: '图标规范',
+      }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '新建图标规范' }));
+
+    const iconSpecDialog = screen.getByRole('dialog', { name: '生成规范' });
+    ['玩法设定', '美术风格'].forEach((title) => {
+      expect(within(iconSpecDialog).getByText(title)).toBeTruthy();
+    });
+  });
+
+  it('defaults character and icon generation to nanobanana2 model options', async () => {
+    render(<ImageCanvasEditorView />);
+    await screen.findByAltText('画布图片：拼图素材');
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', {
+      name: '生成角色形象',
+    });
+    expect(
+      within(characterPanel).getByRole('button', {
+        name: '生成图片尺寸 1:1·1K',
+      }),
+    ).toBeTruthy();
+    expect(
+      within(characterPanel).getByRole('button', {
+        name: '生成图片模型 nanobanana2',
+      }),
+    ).toBeTruthy();
+    const characterDimensionsPanel =
+      openGenerationDimensionsPanel(characterPanel);
+    expect(within(characterDimensionsPanel).getByText(/^(?:比例|Aspect ratio)$/u)).toBeTruthy();
+    expect(within(characterDimensionsPanel).getByText(/^(?:尺寸|Size)$/u)).toBeTruthy();
+    expect(
+      within(characterDimensionsPanel).getByRole('button', { name: /^(?:比例 )?1:1$/u }),
+    ).toBeTruthy();
+    expect(
+      within(characterDimensionsPanel).getByRole('button', { name: /^(?:尺寸 )?1K$/u }),
+    ).toBeTruthy();
+    const characterModelPanel = openGenerationModelPanel(characterPanel);
+    expect(
+      within(characterModelPanel).getByRole('button', {
+        name: /nanobanana2/u,
+      }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    expect(
+      within(iconPanel).getByRole('button', {
+        name: '生成图片尺寸 1:1·1K',
+      }),
+    ).toBeTruthy();
+    expect(
+      within(iconPanel).getByRole('button', {
+        name: '生成图片模型 nanobanana2',
+      }),
+    ).toBeTruthy();
+  });
+
+  it('submits character generation with default model and dimension options', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,character-model-options',
+      width: 1024,
+      height: 1536,
+      sourceType: 'generated',
+      prompt: '高个子游侠',
+      actualPrompt: '高个子游侠',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'character-model-options-1',
+    });
+    render(<ImageCanvasEditorView />);
+    await screen.findByAltText('画布图片：拼图素材');
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', {
+      name: '生成角色形象',
+    });
+    fireEvent.change(within(characterPanel).getByLabelText('角色设定'), {
+      target: { value: '高个子游侠' },
+    });
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '生成' }),
+    );
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'character',
+          prompt: '高个子游侠',
+          model: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+        }),
+      );
+    });
+  });
+
+  it('remembers the last selected image model for character and icon generation', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,character-gpt-model',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '蓝衣剑士',
+      actualPrompt: '蓝衣剑士',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'character-gpt-model-1',
+    });
+    generateEditorIconSpritesheetMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,sheet-gpt-model',
+      spritesheetWidth: 1024,
+      spritesheetHeight: 1024,
+      iconImageSrcs: [
+        {
+          name: '返回按钮',
+          imageSrc: 'data:image/png;base64,back',
+          width: 128,
+          height: 128,
+        },
+      ],
+      prompt: '图标 prompt',
+      actualPrompt: '图标 prompt',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'icon-gpt-model-1',
+      priceMudPoints: 20,
+    });
+    render(<ImageCanvasEditorView />);
+    await screen.findByAltText('画布图片：拼图素材');
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', {
+      name: '生成角色形象',
+    });
+    selectGenerationModel(characterPanel, 'gpt-image-2');
+    selectGenerationDimensions(characterPanel, '2:3', '2K');
+    fireEvent.change(within(characterPanel).getByLabelText('角色设定'), {
+      target: { value: '蓝衣剑士' },
+    });
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '生成' }),
+    );
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'character',
+          prompt: '蓝衣剑士',
+          model: 'gpt-image-2',
+          aspectRatio: '2:3',
+          imageSize: '2K',
+        }),
+      );
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    expect(
+      within(iconPanel).getByRole('button', {
+        name: '生成图片模型 gpt-image-2',
+      }),
+    ).toBeTruthy();
+    fireEvent.click(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+    await userEvent.upload(
+      screen.getByLabelText('上传媒体文件'),
+      new File(['icon-spec'], '图标规范.png', { type: 'image/png' }),
+    );
+    await waitFor(() => {
+      expect(
+        within(screen.getByRole('dialog', { name: '生成图标素材' })).getByRole(
+          'button',
+          { name: '图标规范.png' },
+        ),
+      ).toBeTruthy();
+    });
+    fireEvent.click(
+      within(screen.getByRole('dialog', { name: '生成图标素材' })).getByRole(
+        'button',
+        { name: '生成' },
+      ),
+    );
+
+    await waitFor(() => {
+      expect(generateEditorIconSpritesheetMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          model: 'gpt-image-2',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          priceMudPoints: 20,
+        }),
+      );
+    });
+  });
+
+  it('keeps the bottom AI toolbar visible while generation panels are open', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+    expect(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).toBeTruthy();
+  });
+
+  it('keeps existing generation placeholders when another bottom generation object is created', async () => {
+    render(<ImageCanvasEditorView />);
+    await act(async () => {});
+
+    const bottomToolbar = screen.getByRole('toolbar', {
+      name: 'AI画布工具栏',
+    });
+    fireEvent.click(
+      within(bottomToolbar).getByRole('button', { name: '生成规范' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '角色规范' }));
+
+    expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
+    expect(screen.getByRole('dialog', { name: '生成规范' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+
+    expect(screen.getByLabelText('规范生成占位图')).toBeTruthy();
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+
+    fireEvent.pointerDown(screen.getByLabelText('规范生成占位图'), {
+      button: 0,
+      pointerId: 1701,
+      clientX: 180,
+      clientY: 180,
+    });
+
+    expect(screen.getByRole('dialog', { name: '生成规范' })).toBeTruthy();
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+  });
+
+  it('keeps archived generation logic using the latest placeholder when another object is active', async () => {
+    let resolveGeneration!: (value: unknown) => void;
+    generateEditorImageMock.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveGeneration = resolve;
+      }),
+    );
+    render(<ImageCanvasEditorView />);
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '生成中切换后仍保留位置' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    const originalFrame = screen.getByLabelText('图像生成占位图');
+    const originalLeft = Number.parseFloat(
+      (originalFrame as HTMLElement).style.left,
+    );
+    const originalTop = Number.parseFloat(
+      (originalFrame as HTMLElement).style.top,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    expect(screen.getByLabelText('图像生成占位图')).toBeTruthy();
+    const characterFrame = screen.getByLabelText('角色生成占位图');
+    expect(characterFrame).toBeTruthy();
+
+    dispatchPointerEvent(
+      screen.getByLabelText('图像生成占位图'),
+      'pointerdown',
+      {
+        button: 0,
+        pointerId: 1702,
+        clientX: 500,
+        clientY: 260,
+      },
+    );
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      pointerId: 1702,
+      clientX: 650,
+      clientY: 390,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointerup', {
+      pointerId: 1702,
+      clientX: 650,
+      clientY: 390,
+    });
+    const movedFrame = screen.getByLabelText('图像生成占位图');
+    const movedLeft = Number.parseFloat((movedFrame as HTMLElement).style.left);
+    const movedTop = Number.parseFloat((movedFrame as HTMLElement).style.top);
+    expect(movedLeft).toBeGreaterThan(originalLeft);
+    expect(movedTop).toBeGreaterThan(originalTop);
+
+    dispatchPointerEvent(characterFrame, 'pointerdown', {
+      button: 0,
+      pointerId: 1703,
+      clientX: 360,
+      clientY: 240,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointerup', {
+      pointerId: 1703,
+      clientX: 360,
+      clientY: 240,
+    });
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+
+    await act(async () => {
+      resolveGeneration({
+        imageSrc: 'data:image/png;base64,YXJjaGl2ZWQtbG9naWM=',
+        width: 1024,
+        height: 1024,
+        sourceType: 'generated',
+        prompt: '生成中切换后仍保留位置',
+        actualPrompt: '生成中切换后仍保留位置',
+        model: 'gpt-image-2',
+        provider: 'VectorEngine',
+        taskId: 'editor-archived-generation-1',
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
+    });
+    const generatedLayer = screen
+      .getByAltText(/画布图片：生成图片/)
+      .closest('button') as HTMLElement;
+    const expectedLayerLeft =
+      movedLeft +
+      Number.parseFloat((movedFrame as HTMLElement).style.width) / 2 -
+      512;
+    const expectedLayerTop =
+      movedTop +
+      Number.parseFloat((movedFrame as HTMLElement).style.height) / 2 -
+      512;
+    expect(Number.parseFloat(generatedLayer.style.left)).toBeCloseTo(
+      expectedLayerLeft,
+      1,
+    );
+    expect(Number.parseFloat(generatedLayer.style.top)).toBeCloseTo(
+      expectedLayerTop,
+      1,
+    );
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+  });
+
+  it('renders editor popup menus outside clipped local containers', () => {
+    render(<ImageCanvasEditorView />);
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    fireEvent.click(
+      within(bottomToolbar).getByRole('button', { name: '生成规范' }),
+    );
+    const specMenu = screen.getByRole('menu', { name: '生成规范类型' });
+
+    expect(bottomToolbar.contains(specMenu)).toBe(false);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', { name: '生成角色形象' });
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '角色规范' }),
+    );
+    const referenceRow = characterPanel.querySelector(
+      '.image-canvas-editor__reference-strip',
+    );
+    const sourceMenu = screen.getByRole('menu', { name: '角色规范来源' });
+
+    if (!referenceRow) {
+      throw new Error('角色生成面板应包含参考图区域');
+    }
+    expect(referenceRow.contains(sourceMenu)).toBe(false);
+    expect(sourceMenu.className).toContain('platform-floating-menu--top-start');
+
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '上传常规参考图' }),
+    );
+    const regularReferenceMenu = screen.getByRole('menu', {
+      name: '常规参考图来源',
+    });
+    expect(referenceRow.contains(regularReferenceMenu)).toBe(false);
+    expect(regularReferenceMenu.className).toContain(
+      'platform-floating-menu--top-start',
+    );
+  });
+
+  it('uses Lovart-style reference tiles in the character generation panel', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', { name: '生成角色形象' });
+    const specTile = within(characterPanel).getByRole('button', {
+      name: '角色规范',
+    });
+    const uploadTile = within(characterPanel).getByRole('button', {
+      name: '上传常规参考图',
+    });
+
+    expect(specTile.className).toContain('image-canvas-editor__reference-chip');
+    expect(uploadTile.className).toContain(
+      'image-canvas-editor__reference-chip',
+    );
+    expect(
+      specTile.querySelector('.image-canvas-editor__reference-chip-icon'),
+    ).toBeTruthy();
+    expect(
+      uploadTile.querySelector('.image-canvas-editor__reference-chip-icon'),
+    ).toBeTruthy();
+  });
+
+  it('uses one direct text input for icon asset descriptions', async () => {
+    render(<ImageCanvasEditorView />);
+
+    await waitFor(() => {
+      expect(loadOrCreateRecentEditorProjectMock).toHaveBeenCalled();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    expect(iconPanel.style.width).toBe('');
+    expect(
+      iconPanel.querySelector('.image-canvas-editor__icon-description-list'),
+    ).toBeNull();
+    expect(
+      iconPanel.querySelector('.image-canvas-editor__icon-description-card'),
+    ).toBeNull();
+    expect(
+      iconPanel.querySelector('.image-canvas-editor__icon-spec-card'),
+    ).toBeTruthy();
+
+    fireEvent.change(
+      within(iconPanel).getByRole('textbox', { name: '素材描述' }),
+      { target: { value: '返回按钮\n设置按钮\n提示按钮' } },
+    );
+
+    expect(within(iconPanel).getAllByRole('textbox')).toHaveLength(1);
+    expect(
+      within(iconPanel).queryByRole('button', { name: '添加素材描述' }),
+    ).toBeNull();
+  });
+
+  it('hides the active generation panel and clears image selection after canvas background focus', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,Zm9jdXMtY2xlYXI=',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '发光蘑菇角色',
+      actualPrompt: '发光蘑菇角色',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-focus-clear-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '发光蘑菇角色' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    const generatedImage = await screen.findByAltText(/画布图片：生成图片/u);
+    const generatedLayerButton = generatedImage.closest('button')!;
+    expect(generatedLayerButton.className).toContain(
+      'image-canvas-editor__layer--selected',
+    );
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+
+    fireEvent.pointerDown(screen.getByLabelText('画布工作区'), {
+      button: 0,
+      pointerId: 261,
+      clientX: 40,
+      clientY: 40,
+    });
+
+    expect(screen.queryByRole('dialog', { name: '生成图片' })).toBeNull();
+    expect(generatedLayerButton.className).not.toContain(
+      'image-canvas-editor__layer--selected',
+    );
+  });
+
+  it('hides a newly created placeholder panel after canvas background focus', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+
+    fireEvent.pointerDown(screen.getByLabelText('画布工作区'), {
+      button: 0,
+      pointerId: 262,
+      clientX: 40,
+      clientY: 40,
+    });
+
+    expect(screen.queryByRole('dialog', { name: '生成角色形象' })).toBeNull();
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+  });
+
+  it('builds UI spec prompts from two fields and uses 2K landscape generation', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,c3BlYy11aQ==',
+      width: 2048,
+      height: 1152,
+      sourceType: 'generated',
+      prompt: 'UI规范提示词',
+      actualPrompt: 'UI规范提示词',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-spec-ui-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(
+      within(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).getByRole(
+        'button',
+        { name: '生成规范' },
+      ),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '图标规范' }));
+
+    expect((screen.getByLabelText('玩法设定') as HTMLInputElement).value).toBe(
+      '抓娃娃题材的抓大鹅玩法',
+    );
+    expect((screen.getByLabelText('美术风格') as HTMLInputElement).value).toBe(
+      '毛茸茸',
+    );
+    fireEvent.change(screen.getByLabelText('玩法设定'), {
+      target: { value: '消除类派对玩法' },
+    });
+    fireEvent.change(screen.getByLabelText('美术风格'), {
+      target: { value: '糖果玻璃拟物' },
+    });
+    fireEvent.click(
+      within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
+        'button',
+        { name: '提交生成规范' },
+      ),
+    );
+
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'spec',
+        model: 'gpt-image-2',
+        size: '2048x1152',
+        aspectRatio: '16:9',
+        imageSize: '2K',
+        prompt: expect.stringContaining('生成一张完整游戏UI规范汇总设定展板'),
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetKind: 'icon-spec',
+      }),
+    );
+    const prompt = generateEditorImageMock.mock.calls[0]?.[0]?.prompt ?? '';
+    expect(prompt).toContain('玩法设定：消除类派对玩法');
+    expect(prompt).toContain('美术风格：糖果玻璃拟物');
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：图标规范/)).toBeTruthy();
+    });
+    expect(screen.getAllByText('图标规范').length).toBeGreaterThan(0);
+  });
+
+  it('uses the custom spec prompt without template rewriting', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,c3BlYy1jdXN0b20=',
+      width: 2048,
+      height: 1152,
+      sourceType: 'generated',
+      prompt: '自定义规范提示词',
+      actualPrompt: '自定义规范提示词',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-spec-custom-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(
+      within(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).getByRole(
+        'button',
+        { name: '生成规范' },
+      ),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '自定义规范' }));
+    fireEvent.change(screen.getByLabelText('自定义规范提示词'), {
+      target: { value: '  生成一张武器图标规范展板  ' },
+    });
+    fireEvent.click(
+      within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
+        'button',
+        { name: '提交生成规范' },
+      ),
+    );
+
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'spec',
+        model: 'gpt-image-2',
+        size: '2048x1152',
+        aspectRatio: '16:9',
+        imageSize: '2K',
+        prompt: '生成一张武器图标规范展板',
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetKind: 'spec',
+      }),
+    );
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：自定义规范/)).toBeTruthy();
+    });
+    expect(screen.getByText('规范')).toBeTruthy();
+  });
+
+  it('keeps spec reference source menu actions clickable from the portal', async () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(
+      within(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).getByRole(
+        'button',
+        { name: '生成规范' },
+      ),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '角色规范' }));
+
+    const specDialog = screen.getByRole('dialog', { name: '生成规范' });
+    await userEvent.click(
+      within(specDialog).getByRole('button', { name: '参考图' }),
+    );
+    await userEvent.click(
+      within(screen.getByRole('menu', { name: '参考图来源' })).getByRole(
+        'menuitem',
+        { name: '从画布中选择' },
+      ),
+    );
+
+    expect(
+      screen.getByText('请选择画布中的图片作为参考图，按 Esc 退出'),
+    ).toBeTruthy();
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 190,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    expect(
+      within(screen.getByRole('dialog', { name: '生成规范' })).getByText(
+        '拼图素材',
+      ),
+    ).toBeTruthy();
+
+    await userEvent.click(
+      within(screen.getByRole('dialog', { name: '生成规范' })).getByRole(
+        'button',
+        { name: '参考图' },
+      ),
+    );
+    await userEvent.click(
+      within(screen.getByRole('menu', { name: '参考图来源' })).getByRole(
+        'menuitem',
+        { name: '上传图片' },
+      ),
+    );
+    await userEvent.upload(
+      screen.getByLabelText('上传媒体文件'),
+      new File(['spec-reference'], '规范上传.png', { type: 'image/png' }),
+    );
+
+    await waitFor(() => {
+      expect(
+        within(screen.getByRole('dialog', { name: '生成规范' })).getByText(
+          '规范上传.png',
+        ),
+      ).toBeTruthy();
+    });
+  });
+
+  it('supports character generation from a picked canvas spec and numbered references', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,Y2hhcmFjdGVy',
+      objectKey:
+        'generated-character-drafts/editor/character-images/editor-character-1/image.png',
+      assetObjectId: 'asset-object-editor-character-1',
+      width: 2048,
+      height: 2048,
+      sourceType: 'generated',
+      prompt: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+      actualPrompt: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-character-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+
+    const characterPanel = screen.getByRole('dialog', { name: '生成角色形象' });
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+    expect(
+      within(characterPanel).getByRole('button', { name: '角色规范' }),
+    ).toBeTruthy();
+
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '角色规范' }),
+    );
+    const specSourceMenu = screen.getByRole('menu', {
+      name: '角色规范来源',
+    });
+    fireEvent.click(
+      within(specSourceMenu).getByRole('menuitem', { name: '从画布中选择' }),
+    );
+    expect(
+      screen.getByText('请选择画布中的图片作为角色规范，按 Esc 退出'),
+    ).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 170,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    expect(within(characterPanel).getByText('拼图素材')).toBeTruthy();
+    expect(
+      screen.queryByText('请选择画布中的图片作为角色规范，按 Esc 退出'),
+    ).toBeNull();
+
+    const canvasReferenceLayer = screen
+      .getByAltText('画布图片：大鱼素材')
+      .closest('button')!;
+    expect(canvasReferenceLayer.className).not.toContain(
+      'image-canvas-editor__layer--selected',
+    );
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '上传常规参考图' }),
+    );
+    const regularReferenceMenu = screen.getByRole('menu', {
+      name: '常规参考图来源',
+    });
+    fireEvent.click(
+      within(regularReferenceMenu).getByRole('menuitem', {
+        name: '从画布中选择',
+      }),
+    );
+    expect(
+      screen.getByText('请选择画布中的图片作为常规参考图，按 Esc 退出'),
+    ).toBeTruthy();
+    fireEvent.pointerDown(canvasReferenceLayer, {
+      button: 0,
+      pointerId: 171,
+      clientX: 180,
+      clientY: 120,
+    });
+    expect(
+      screen.queryByText('请选择画布中的图片作为常规参考图，按 Esc 退出'),
+    ).toBeNull();
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+    expect(canvasReferenceLayer.className).not.toContain(
+      'image-canvas-editor__layer--selected',
+    );
+    expect(within(characterPanel).getByText('大鱼素材')).toBeTruthy();
+
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '上传常规参考图' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+    await userEvent.upload(
+      screen.getByLabelText('上传媒体文件'),
+      new File(['reference'], '常规参考.png', { type: 'image/png' }),
+    );
+    await waitFor(() => {
+      expect(within(characterPanel).getByText('常规参考.png')).toBeTruthy();
+    });
+
+    fireEvent.change(within(characterPanel).getByLabelText('角色设定'), {
+      target: { value: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。' },
+    });
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '生成' }),
+    );
+
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'character',
+        prompt: '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+        referenceImageSrcs: [
+          '/creation-type-references/puzzle.webp',
+          '/creation-type-references/big-fish.webp',
+          expect.stringMatching(/^data:image\/png;base64,/u),
+        ],
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetKind: 'character',
+        generationInputs: expect.objectContaining({
+          fields: expect.arrayContaining([
+            expect.objectContaining({
+              title: '角色设定',
+              value:
+                '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+            }),
+          ]),
+        }),
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：角色形象/u)).toBeTruthy();
+    });
+    expect(screen.getByText('角色')).toBeTruthy();
+    fireEvent.click(
+      screen.getAllByRole('button', {
+        name: /查看角色形象 .*图片信息/u,
+      })[0]!,
+    );
+    const characterInfoPanel = screen.getByRole('dialog', {
+      name: '图片信息',
+    });
+    expect(within(characterInfoPanel).queryByText('Prompt')).toBeNull();
+    expect(within(characterInfoPanel).getByText('生成输入')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('角色设定')).toBeTruthy();
+    expect(
+      within(characterInfoPanel).getByText(
+        '银发游侠，蓝色披风，弓箭手，适合像素风战棋。',
+      ),
+    ).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('角色规范')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('拼图素材')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('常规参考图 1')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('大鱼素材')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('常规参考图 2')).toBeTruthy();
+    expect(within(characterInfoPanel).getByText('常规参考.png')).toBeTruthy();
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: expect.stringMatching(/角色形象/u),
+              objectKey:
+                'generated-character-drafts/editor/character-images/editor-character-1/image.png',
+              assetObjectId: 'asset-object-editor-character-1',
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('removes the active character generation placeholder with Backspace', async () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+
+    expect(screen.getByLabelText('角色生成占位图')).toBeTruthy();
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+
+    await act(async () => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(screen.queryByLabelText('角色生成占位图')).toBeNull();
+    expect(screen.queryByRole('dialog', { name: '生成角色形象' })).toBeNull();
+    expect(screen.getByAltText('画布图片：拼图素材')).toBeTruthy();
+  });
+
+  it('opens icon asset generation panel, only picks icon specs, and lays generated icons on canvas', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-icons',
+      title: '图标素材画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-plain',
+          resourceId: 'resource-plain',
+          title: '普通参考图',
+          src: 'data:image/png;base64,plain',
+          x: 80,
+          y: 80,
+          width: 120,
+          height: 120,
+          originalWidth: 512,
+          originalHeight: 512,
+          zIndex: 10,
+          sourceType: 'uploaded',
+        },
+        {
+          layerId: 'layer-icon-spec',
+          resourceId: 'resource-icon-spec',
+          title: '清爽按钮图标规范',
+          src: 'data:image/png;base64,icon-spec',
+          x: 240,
+          y: 80,
+          width: 160,
+          height: 120,
+          originalWidth: 2048,
+          originalHeight: 1152,
+          zIndex: 11,
+          sourceType: 'generated',
+          assetKind: 'icon-spec',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-15T00:00:00.000Z',
+    });
+    generateEditorIconSpritesheetMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,sheet',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      iconImageSrcs: [
+        {
+          name: '返回按钮',
+          imageSrc: 'data:image/png;base64,back-icon',
+          width: 96,
+          height: 96,
+        },
+        {
+          name: '设置按钮',
+          imageSrc: 'data:image/png;base64,setting-icon',
+          width: 96,
+          height: 96,
+        },
+      ],
+      prompt: '图标 prompt',
+      actualPrompt: '图标 prompt',
+      model: 'gemini-3.1-flash-image-preview',
+      provider: 'VectorEngine',
+      taskId: 'icon-task-1',
+      priceMudPoints: 12,
+    });
+    render(<ImageCanvasEditorView />);
+
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：普通参考图')).toBeTruthy();
+      expect(screen.getByAltText('画布图片：清爽按钮图标规范')).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    expect(screen.getByLabelText('图标素材生成占位图')).toBeTruthy();
+    expect(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    ).toBeTruthy();
+    expect(
+      (
+        within(iconPanel).getByRole('textbox', {
+          name: '素材描述',
+        }) as HTMLTextAreaElement
+      ).value,
+    ).toBe('返回按钮\n设置按钮\n下一关按钮\n提示按钮\n原图按钮\n冻结按钮');
+
+    fireEvent.click(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+    expect(
+      screen.getByText('请选择画布中的图标规范，按 Esc 退出'),
+    ).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：普通参考图').closest('button')!,
+      {
+        button: 0,
+        pointerId: 180,
+        clientX: 100,
+        clientY: 100,
+      },
+    );
+    expect(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    ).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：清爽按钮图标规范').closest('button')!,
+      {
+        button: 0,
+        pointerId: 181,
+        clientX: 260,
+        clientY: 100,
+      },
+    );
+    expect(
+      within(iconPanel).getByRole('button', { name: '清爽按钮图标规范' }),
+    ).toBeTruthy();
+    expect(
+      screen.queryByText('请选择画布中的图标规范，按 Esc 退出'),
+    ).toBeNull();
+
+    fireEvent.change(
+      within(iconPanel).getByRole('textbox', { name: '素材描述' }),
+      {
+        target: { value: '返回按钮\n设置按钮' },
+      },
+    );
+    fireEvent.click(within(iconPanel).getByRole('button', { name: '生成' }));
+
+    expect(generateEditorIconSpritesheetMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        referenceImageSrc: 'data:image/png;base64,icon-spec',
+        iconDescriptions: ['返回按钮', '设置按钮'],
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+        priceMudPoints: 12,
+        projectId: 'editor-project-icons',
+        assetFolderId: 'project',
+        generationInputs: expect.objectContaining({
+          fields: expect.arrayContaining([
+            expect.objectContaining({
+              title: '素材描述',
+              value: '返回按钮\n设置按钮',
+            }),
+          ]),
+        }),
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：返回按钮')).toBeTruthy();
+      expect(screen.getByAltText('画布图片：设置按钮')).toBeTruthy();
+    });
+    expect(screen.queryByLabelText('图标素材生成占位图')).toBeNull();
+    expect(screen.getAllByText('图标')).toHaveLength(2);
+    fireEvent.click(
+      screen.getAllByRole('button', { name: '查看返回按钮图片信息' })[0]!,
+    );
+    const iconInfoPanel = screen.getByRole('dialog', { name: '图片信息' });
+    expect(within(iconInfoPanel).queryByText('Prompt')).toBeNull();
+    expect(within(iconInfoPanel).getByText('生成输入')).toBeTruthy();
+    expect(within(iconInfoPanel).getByText('素材描述')).toBeTruthy();
+    expect(
+      within(iconInfoPanel).getByText(
+        (_, element) => element?.textContent === '返回按钮\n设置按钮',
+      ),
+    ).toBeTruthy();
+    expect(within(iconInfoPanel).getByText('图标规范')).toBeTruthy();
+    expect(within(iconInfoPanel).getByText('清爽按钮图标规范')).toBeTruthy();
+  });
+
+  it('allows icon asset generation to reference icon specs created from the renamed spec entry', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,cmVuYW1lZC1pY29uLXNwZWM=',
+      width: 2048,
+      height: 1152,
+      sourceType: 'generated',
+      prompt: '图标规范提示词',
+      actualPrompt: '图标规范提示词',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-icon-spec-renamed-1',
+    });
+    generateEditorIconSpritesheetMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,cmVuYW1lZC1zaGVldA==',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      iconImageSrcs: [
+        {
+          name: '背包按钮',
+          imageSrc: 'data:image/png;base64,YmFncGFjay1pY29u',
+          width: 96,
+          height: 96,
+        },
+      ],
+      prompt: '图标 prompt',
+      actualPrompt: '图标 prompt',
+      model: 'gemini-3.1-flash-image-preview',
+      provider: 'VectorEngine',
+      taskId: 'icon-task-renamed-spec-1',
+      priceMudPoints: 12,
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(
+      within(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).getByRole(
+        'button',
+        { name: '生成规范' },
+      ),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '图标规范' }));
+    const specDialog = screen.getByRole('dialog', { name: '生成规范' });
+    fireEvent.change(within(specDialog).getByLabelText('玩法设定'), {
+      target: { value: '背包整理玩法' },
+    });
+    fireEvent.click(
+      within(specDialog).getByRole('button', { name: '提交生成规范' }),
+    );
+
+    const generatedSpec = await screen.findByAltText(/画布图片：图标规范/u);
+    expect(generateEditorImageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'spec',
+        prompt: expect.stringContaining('背包整理玩法'),
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+        assetKind: 'icon-spec',
+        generationInputs: expect.objectContaining({
+          fields: expect.arrayContaining([
+            expect.objectContaining({
+              title: '玩法设定',
+              value: '背包整理玩法',
+            }),
+          ]),
+        }),
+      }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图标素材' }));
+    const iconPanel = screen.getByRole('dialog', { name: '生成图标素材' });
+    fireEvent.click(
+      within(iconPanel).getByRole('button', { name: '图标规范' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+    fireEvent.pointerDown(generatedSpec.closest('button')!, {
+      button: 0,
+      pointerId: 182,
+      clientX: 260,
+      clientY: 100,
+    });
+
+    expect(
+      within(iconPanel).getByRole('button', { name: /^图标规范 \d+$/u }),
+    ).toBeTruthy();
+    expect(
+      screen.queryByText('请选择画布中的图标规范，按 Esc 退出'),
+    ).toBeNull();
+
+    fireEvent.change(
+      within(iconPanel).getByRole('textbox', { name: '素材描述' }),
+      {
+        target: { value: '背包按钮' },
+      },
+    );
+    fireEvent.click(within(iconPanel).getByRole('button', { name: '生成' }));
+
+    expect(generateEditorIconSpritesheetMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        referenceImageSrc: 'data:image/png;base64,cmVuYW1lZC1pY29uLXNwZWM=',
+        iconDescriptions: ['背包按钮'],
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+        priceMudPoints: 12,
+        projectId: 'editor-project-default',
+        assetFolderId: 'project',
+      }),
+    );
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：背包按钮')).toBeTruthy();
+    });
+  });
+
+  it('exits character generation canvas picking with Escape', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成角色形象' }));
+    const characterPanel = screen.getByRole('dialog', { name: '生成角色形象' });
+    fireEvent.click(
+      within(characterPanel).getByRole('button', { name: '角色规范' }),
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+
+    expect(
+      screen.getByText('请选择画布中的图片作为角色规范，按 Esc 退出'),
+    ).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: 'Escape' });
+
+    expect(
+      screen.queryByText('请选择画布中的图片作为角色规范，按 Esc 退出'),
+    ).toBeNull();
+    expect(screen.getByRole('dialog', { name: '生成角色形象' })).toBeTruthy();
+  });
+
+  it('only exposes character animation generation for character layers and submits the panel payload', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-character-animation',
+      title: '角色动画画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-character',
+          resourceId: 'resource-character',
+          title: '市场老妇人',
+          src: 'data:image/png;base64,character',
+          x: 160,
+          y: 140,
+          width: 320,
+          height: 320,
+          originalWidth: 1024,
+          originalHeight: 1024,
+          zIndex: 2,
+          sourceType: 'generated',
+          objectKey:
+            'generated-character-drafts/editor/character-images/source/image.png',
+          assetKind: 'character',
+        },
+        {
+          layerId: 'layer-prop',
+          resourceId: 'resource-prop',
+          title: '普通道具',
+          src: 'data:image/png;base64,prop',
+          x: 520,
+          y: 140,
+          width: 280,
+          height: 220,
+          originalWidth: 700,
+          originalHeight: 550,
+          zIndex: 1,
+          sourceType: 'uploaded',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-15T00:00:00.000Z',
+    });
+    generateEditorCharacterAnimationMock.mockResolvedValueOnce({
+      taskId: 'character-animation-task-1',
+      model: 'seedance2.0-fast',
+      prompt: '生成游戏角色动画\n动作描述：\n待机',
+      previewVideoPath: '/generated-character-drafts/editor/preview.mp4',
+      frames: Array.from({ length: 48 }, (_, index) => ({
+        frameIndex: index + 1,
+        imageSrc: `/generated-character-drafts/editor/frame${index + 1}.png`,
+        width: 1024,
+        height: 1024,
+      })),
+      frameCount: 48,
+      durationSeconds: 6,
+      fps: 8,
+      priceMudPoints: 120,
+    });
+    render(<ImageCanvasEditorView />);
+
+    const propLayer = await screen.findByAltText('画布图片：普通道具');
+    fireEvent.click(propLayer.closest('button')!);
+    expect(screen.queryByRole('button', { name: '生成动画' })).toBeNull();
+    fireEvent.contextMenu(propLayer.closest('button')!, {
+      clientX: 220,
+      clientY: 180,
+    });
+    expect(screen.queryByRole('menuitem', { name: '生成动画' })).toBeNull();
+
+    const characterLayer = screen.getByAltText('画布图片：市场老妇人');
+    fireEvent.click(characterLayer.closest('button')!);
+    expect(screen.getByText('角色')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '生成动画' })).toBeTruthy();
+    expect(screen.queryByRole('dialog', { name: '重绘图片' })).toBeNull();
+    expect(
+      screen.queryByRole('dialog', { name: '快速编辑图片' }),
+    ).toBeNull();
+    expect(
+      screen.queryByRole('dialog', { name: '角色动画生成面板' }),
+    ).toBeNull();
+    fireEvent.contextMenu(characterLayer.closest('button')!, {
+      clientX: 260,
+      clientY: 220,
+    });
+    expect(screen.getByRole('menuitem', { name: '生成动画' })).toBeTruthy();
+
+    expect(screen.queryByRole('dialog', { name: '重绘图片' })).toBeNull();
+    expect(
+      screen.queryByRole('dialog', { name: '快速编辑图片' }),
+    ).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '生成动画' }));
+    expect(
+      screen.getByRole('button', { name: '角色动作生成占位图' }),
+    ).toBeTruthy();
+    expect(screen.getByText('Action Generator')).toBeTruthy();
+    expect(screen.getByText('动作')).toBeTruthy();
+    const panel = screen.getByRole('dialog', { name: '角色动画生成面板' });
+    expect(panel.className).toContain(
+      'image-canvas-editor__generation-composer--character-animation',
+    );
+    expect(
+      within(panel).getByRole('button', {
+        name: '动画参数 同图尺寸 · 4秒 · 480p',
+      }),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', { name: '生成40泥点' }),
+    ).toBeTruthy();
+    for (const actionLabel of [
+      '待机',
+      '行走',
+      '奔跑',
+      '跳跃',
+      '攻击',
+      '受击',
+      '倒下',
+    ]) {
+      expect(
+        within(panel).getByRole('button', { name: actionLabel }),
+      ).toBeTruthy();
+    }
+    fireEvent.click(within(panel).getByRole('button', { name: '待机' }));
+    expect(
+      (within(panel).getByLabelText('动画描述') as HTMLTextAreaElement).value,
+    ).toContain('待机');
+    const longPrompt = '走'.repeat(4100);
+    fireEvent.change(within(panel).getByLabelText('动画描述'), {
+      target: { value: longPrompt },
+    });
+    expect(
+      (within(panel).getByLabelText('动画描述') as HTMLTextAreaElement).value,
+    ).toHaveLength(4000);
+    const precisePrompt =
+      'The elderly market woman gently shifts weight while the basket sways.';
+    fireEvent.change(within(panel).getByLabelText('动画描述'), {
+      target: { value: precisePrompt },
+    });
+    expect(
+      within(panel).getByLabelText(`生成文本：${precisePrompt}`),
+    ).toBeTruthy();
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: '动画参数 同图尺寸 · 4秒 · 480p',
+      }),
+    );
+    const animationMenu = screen.getByRole('menu', { name: '动画参数选项' });
+    fireEvent.click(
+      within(animationMenu).getByRole('button', { name: '清晰度 720p' }),
+    );
+    fireEvent.click(
+      within(animationMenu).getByRole('button', { name: '比例 16:9' }),
+    );
+    fireEvent.click(
+      within(animationMenu).getByRole('button', { name: '时长 48帧·6秒' }),
+    );
+    expect(
+      screen.getByRole('menu', { name: '动画参数选项' }),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', {
+        name: '动画参数 16:9 · 6秒 · 720p',
+      }),
+    ).toBeTruthy();
+    fireEvent.click(within(panel).getByRole('button', { name: '生成120泥点' }));
+
+    expect(generateEditorCharacterAnimationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sourceLayerId: 'layer-character',
+        sourceImageSrc:
+          'generated-character-drafts/editor/character-images/source/image.png',
+        sourceWidth: 1024,
+        sourceHeight: 1024,
+        resolution: '720p',
+        ratio: '16:9',
+        frameCount: 48,
+        durationSeconds: 6,
+        priceMudPoints: 120,
+        model: 'seedance2.0-fast',
+      }),
+    );
+    expect(
+      generateEditorCharacterAnimationMock.mock.calls[0]?.[0]?.promptText,
+    ).toBe(precisePrompt);
+    await waitFor(() => {
+      expect(screen.getByLabelText('画布视频：角色动作')).toBeTruthy();
+    });
+    const actionVideo = screen.getByLabelText('画布视频：角色动作');
+    expect(actionVideo.tagName.toLowerCase()).toBe('video');
+    expect(actionVideo.getAttribute('poster')).toBe(
+      '/generated-character-drafts/editor/frame1.png',
+    );
+    expect(actionVideo.hasAttribute('controls')).toBe(true);
+    expect(screen.getByText('动作')).toBeTruthy();
+  });
+
+  it('extracts UI design assets from the floating toolbar and keeps the spritesheet on canvas', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-ui-extract',
+      title: 'UI素材提取画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-ui-design',
+          resourceId: 'resource-ui-design',
+          title: '战斗UI设计图',
+          src: 'data:image/png;base64,dWktZGVzaWdu',
+          x: 120,
+          y: 140,
+          width: 560,
+          height: 315,
+          originalWidth: 2048,
+          originalHeight: 1152,
+          zIndex: 2,
+          sourceType: 'generated',
+          prompt: '战斗UI',
+          actualPrompt: '战斗UI',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'ui-design-task-1',
+          assetKind: 'ui-design',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-18T00:00:00.000Z',
+    });
+    extractEditorUiDesignAssetsMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,dWktc2hlZXQ=',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      iconImageSrcs: [
+        {
+          name: '素材 1',
+          imageSrc: 'data:image/png;base64,YXNzZXQtMQ==',
+          width: 96,
+          height: 96,
+        },
+      ],
+      prompt: '提取画面中的所有独立并整理成spritesheet',
+      actualPrompt: '提取画面中的所有独立并整理成spritesheet',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'ui-extract-task-1',
+      priceMudPoints: 20,
+    });
+    render(<ImageCanvasEditorView />);
+
+    const uiDesignImage = await screen.findByAltText(
+      '画布图片：战斗UI设计图',
+    );
+    fireEvent.pointerDown(uiDesignImage.closest('button')!, {
+      button: 0,
+      pointerId: 156,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 156,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '提取素材' }));
+
+    await waitFor(() => {
+      expect(extractEditorUiDesignAssetsMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceImageSrc: 'data:image/png;base64,dWktZGVzaWdu',
+          projectId: 'editor-project-ui-extract',
+          assetFolderId: 'project',
+          spritesheetLabel: '战斗UI设计图 素材图集',
+          generationInputs: expect.objectContaining({
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                title: '提取提示词',
+                value: '提取画面中的所有独立并整理成spritesheet',
+              }),
+            ]),
+            references: expect.arrayContaining([
+              expect.objectContaining({
+                title: 'UI设计图',
+                label: '战斗UI设计图',
+              }),
+            ]),
+          }),
+        }),
+      );
+    });
+    expect(
+      await screen.findByAltText('画布图片：战斗UI设计图 素材图集'),
+    ).toBeTruthy();
+    expect(screen.getByAltText('画布图片：素材 1')).toBeTruthy();
+    expect(screen.getByText('图集')).toBeTruthy();
+    await waitFor(() => {
+      expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+        'editor-project-ui-extract',
+        expect.objectContaining({
+          sourceType: 'generated',
+          assetKind: 'icon',
+          generationInputs: expect.objectContaining({
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                title: '提取提示词',
+                value: '提取画面中的所有独立并整理成spritesheet',
+              }),
+            ]),
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-ui-extract',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: '战斗UI设计图 素材图集',
+              resourceId: 'resource-editor-project-ui-extract-512',
+            }),
+            expect.objectContaining({
+              title: '素材 1',
+              resourceId: 'resource-editor-project-ui-extract-96',
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('opens quick edit from the floating toolbar, hides the implicit source reference, and generates from a new frame', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-quick-edit',
+      title: '快速编辑画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-quick-source',
+          resourceId: 'resource-quick-source',
+          title: '魔法森林',
+          src: 'data:image/png;base64,c291cmNl',
+          x: 120,
+          y: 140,
+          width: 320,
+          height: 240,
+          originalWidth: 1536,
+          originalHeight: 1024,
+          zIndex: 2,
+          sourceType: 'generated',
+          prompt: '魔法森林原始提示词',
+          actualPrompt: '魔法森林原始提示词',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'source-task-1',
+          assetKind: 'spec',
+        },
+        {
+          layerId: 'layer-quick-extra-ref',
+          resourceId: 'resource-quick-extra-ref',
+          title: '星空参考',
+          src: 'data:image/png;base64,ZXh0cmEtcmVm',
+          x: -420,
+          y: 100,
+          width: 260,
+          height: 260,
+          originalWidth: 512,
+          originalHeight: 512,
+          zIndex: 1,
+          sourceType: 'uploaded',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-15T00:00:00.000Z',
+    });
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,cXVpY2stZWRpdA==',
+      width: 1536,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '增加萤火虫',
+      actualPrompt: '增加萤火虫',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'quick-edit-task-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const sourceImage = await screen.findByAltText('画布图片：魔法森林');
+    fireEvent.pointerDown(sourceImage.closest('button')!, {
+      button: 0,
+      pointerId: 151,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 151,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑' }));
+
+    const quickPanel = screen.getByRole('dialog', { name: '快速编辑图片' });
+    expect(quickPanel.className).toContain(
+      'image-canvas-editor__quick-edit-panel',
+    );
+    expect(within(quickPanel).queryByText('魔法森林')).toBeNull();
+    expect(
+      (
+        within(quickPanel).getByRole('button', {
+          name: '快速编辑尺寸 3:2·1K',
+        }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(false);
+    expect(
+      (
+        within(quickPanel).getByRole('button', {
+          name: '快速编辑模型 gpt-image-2',
+        }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(false);
+    expect(within(quickPanel).queryByLabelText('原图 图1')).toBeNull();
+
+    fireEvent.click(
+      within(quickPanel).getByRole('button', {
+        name: '添加快速编辑参考图',
+      }),
+    );
+    fireEvent.click(
+      within(
+        screen.getByRole('menu', { name: '快速编辑参考图来源' }),
+      ).getByRole('menuitem', { name: '从画布中选择' }),
+    );
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：星空参考').closest('button')!,
+      {
+        button: 0,
+        pointerId: 152,
+        clientX: 140,
+        clientY: 120,
+      },
+    );
+
+    const updatedQuickPanel = screen.getByRole('dialog', {
+      name: '快速编辑图片',
+    });
+    expect(within(updatedQuickPanel).getByText('星空参考')).toBeTruthy();
+    expect(within(updatedQuickPanel).queryByLabelText('原图 图2')).toBeNull();
+
+    fireEvent.change(within(updatedQuickPanel).getByLabelText('快速编辑提示词'), {
+      target: { value: '参考原图增加萤火虫' },
+    });
+    fireEvent.click(
+      within(updatedQuickPanel).getByRole('button', { name: '生成' }),
+    );
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '参考图2增加萤火虫',
+          size: '1024x683',
+          aspectRatio: '3:2',
+          imageSize: '1K',
+          kind: 'quick-edit',
+          model: 'gpt-image-2',
+          referenceImageSrcs: [
+            'data:image/png;base64,ZXh0cmEtcmVm',
+            'data:image/png;base64,c291cmNl',
+          ],
+          projectId: 'editor-project-quick-edit',
+          assetKind: 'spec',
+          assetFolderId: 'project',
+          assetLabel: '魔法森林 快速编辑',
+          sourceResourceId: 'resource-quick-source',
+          generationInputs: expect.objectContaining({
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                title: '快速编辑提示词',
+                value: '参考图2增加萤火虫',
+              }),
+            ]),
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：魔法森林 快速编辑')).toBeTruthy();
+    });
+    const generatedLayer = screen
+      .getByAltText('画布图片：魔法森林 快速编辑')
+      .closest('button') as HTMLElement;
+    expect(Number.parseFloat(generatedLayer.style.left)).toBe(1688);
+    expect(Number.parseFloat(generatedLayer.style.top)).toBe(140);
+    expect(Number.parseFloat(generatedLayer.style.width)).toBe(1024);
+    expect(Number.parseFloat(generatedLayer.style.height)).toBe(683);
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-quick-edit',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: '魔法森林 快速编辑',
+              resourceId: 'resource-editor-project-quick-edit-1024',
+              width: 1024,
+              height: 683,
+              originalWidth: 1024,
+              originalHeight: 683,
+              x: 1688,
+              y: 140,
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('opens quick edit from the image context menu', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-context-quick-edit',
+      title: '右键快速编辑画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-context-source',
+          resourceId: 'resource-context-source',
+          title: '右键图片',
+          src: 'data:image/png;base64,Y29udGV4dA==',
+          x: 80,
+          y: 90,
+          width: 260,
+          height: 260,
+          originalWidth: 1024,
+          originalHeight: 1024,
+          zIndex: 1,
+          sourceType: 'uploaded',
+          model: 'gpt-image-2',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-15T00:00:00.000Z',
+    });
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,Y29udGV4dC1xdWljaw==',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '换成夜晚',
+      actualPrompt: '换成夜晚',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'context-quick-task-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const contextImage = await screen.findByAltText('画布图片：右键图片');
+    fireEvent.contextMenu(contextImage.closest('button')!, {
+      clientX: 260,
+      clientY: 220,
+    });
+
+    const menu = screen.getByRole('menu', { name: '图片功能面板' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '快速编辑' }),
+    ).toBeTruthy();
+    fireEvent.click(within(menu).getByRole('menuitem', { name: '快速编辑' }));
+
+    const panel = screen.getByRole('dialog', { name: '快速编辑图片' });
+    expect(within(panel).queryByText('右键图片')).toBeNull();
+    fireEvent.change(within(panel).getByLabelText('快速编辑提示词'), {
+      target: { value: '换成夜晚' },
+    });
+    fireEvent.click(within(panel).getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '换成夜晚',
+          referenceImageSrcs: ['data:image/png;base64,Y29udGV4dA=='],
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gpt-image-2',
+          kind: 'quick-edit',
+          projectId: 'editor-project-context-quick-edit',
+          assetFolderId: 'project',
+          assetLabel: '右键图片 快速编辑',
+          sourceResourceId: 'resource-context-source',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByAltText('画布图片：右键图片 快速编辑')).toBeTruthy();
+    });
+  });
+
+  it('converts non-data-url quick edit source images before submitting references', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-public-quick-edit',
+      title: '公开素材快速编辑画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-public-source',
+          resourceId: 'resource-public-source',
+          title: '公开拼图素材',
+          src: '/creation-type-references/puzzle.webp',
+          x: 120,
+          y: 140,
+          width: 320,
+          height: 240,
+          originalWidth: 640,
+          originalHeight: 640,
+          zIndex: 2,
+          sourceType: 'uploaded',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-16T00:00:00.000Z',
+    });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(new Uint8Array([104, 101, 108, 108, 111]), {
+        status: 200,
+        headers: {
+          'Content-Type': 'image/webp',
+        },
+      }),
+    );
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,cHVibGljLXF1aWNr',
+      width: 640,
+      height: 640,
+      sourceType: 'generated',
+      prompt: '改成陶泥风格',
+      actualPrompt: '改成陶泥风格',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'public-quick-edit-task-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const sourceImage = await screen.findByAltText('画布图片：公开拼图素材');
+    fireEvent.pointerDown(sourceImage.closest('button')!, {
+      button: 0,
+      pointerId: 161,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 161,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑' }));
+
+    const quickPanel = screen.getByRole('dialog', { name: '快速编辑图片' });
+    fireEvent.change(within(quickPanel).getByLabelText('快速编辑提示词'), {
+      target: { value: '改成陶泥风格' },
+    });
+    fireEvent.click(within(quickPanel).getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '改成陶泥风格',
+          kind: 'quick-edit',
+          referenceImageSrcs: ['data:image/webp;base64,aGVsbG8='],
+          projectId: 'editor-project-public-quick-edit',
+          assetFolderId: 'project',
+          assetLabel: '公开拼图素材 快速编辑',
+          sourceResourceId: 'resource-public-source',
+        }),
+      );
+    });
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      '/creation-type-references/puzzle.webp',
+      expect.objectContaining({
+        signal: undefined,
+      }),
+    );
+  });
+
+  it('opens generated image info from the corner button and creates a real right-side edit result', async () => {
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,ZmFrZS1pbWFnZQ==',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '一张可修改的生成图',
+      actualPrompt: '一张可修改的生成图',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-real-task-2',
+    });
+    generateEditorImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,ZWRhd24tcmVkcmF3',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '把画面改成黄昏光线',
+      actualPrompt: '把画面改成黄昏光线',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'editor-real-redraw-1',
+    });
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '生成图片' }));
+    fireEvent.change(screen.getByLabelText('生成提示词'), {
+      target: { value: '一张可修改的生成图' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(screen.getByAltText(/画布图片：生成图片/)).toBeTruthy();
+    });
+    const generatedLayer = screen
+      .getByAltText(/画布图片：生成图片/)
+      .closest('button') as HTMLElement;
+    expect(Number.parseFloat(generatedLayer.style.width)).toBe(1024);
+    expect(Number.parseFloat(generatedLayer.style.height)).toBe(1024);
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+
+    const metadataCornerButton = screen.getAllByRole('button', {
+      name: /查看生成图片 .*图片信息/,
+    })[0];
+    if (!metadataCornerButton) {
+      throw new Error('metadata corner button should exist');
+    }
+    expect(metadataCornerButton.className).toContain('bg-black/55');
+    expect(metadataCornerButton.className).toContain(
+      'image-canvas-editor__metadata-corner',
+    );
+    fireEvent.click(metadataCornerButton);
+
+    const metadataDialog = screen.getByRole('dialog', { name: '图片信息' });
+    expect(metadataDialog).toBeTruthy();
+    expect(within(metadataDialog).getByText('图片类型')).toBeTruthy();
+    expect(within(metadataDialog).getByText('生成图片')).toBeTruthy();
+    expect(within(metadataDialog).queryByText('Prompt')).toBeNull();
+    expect(
+      within(metadataDialog).queryByRole('button', { name: '复制Prompt' }),
+    ).toBeNull();
+    expect(within(metadataDialog).getByText('生成输入')).toBeTruthy();
+    expect(within(metadataDialog).getByText('生成提示词')).toBeTruthy();
+    expect(within(metadataDialog).getByText('一张可修改的生成图')).toBeTruthy();
+    expect(within(metadataDialog).getByText('Model')).toBeTruthy();
+    expect(within(metadataDialog).getByText('gpt-image-2')).toBeTruthy();
+    expect(within(metadataDialog).queryByText('Size')).toBeNull();
+    expect(within(metadataDialog).getByText('Resolution')).toBeTruthy();
+    expect(within(metadataDialog).getByText('1024 x 1024 px')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '改造' }));
+    const editDialog = screen.getByRole('dialog', { name: '重绘图片' });
+    expect(editDialog).toBeTruthy();
+    const editPrompt = within(editDialog).getByLabelText('重绘提示词');
+    expect(editPrompt.className).toContain('platform-text-field');
+    expect(editPrompt.className).toContain(
+      'image-canvas-editor__quick-edit-prompt',
+    );
+    fireEvent.change(editPrompt, {
+      target: { value: '把画面改成黄昏光线' },
+    });
+    fireEvent.click(within(editDialog).getByRole('button', { name: '生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          prompt: '把画面改成黄昏光线',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          kind: 'quick-edit',
+          model: 'gpt-image-2',
+          referenceImageSrcs: ['data:image/png;base64,ZmFrZS1pbWFnZQ=='],
+        }),
+      );
+    });
+
+    await waitFor(() => {
+      expect(screen.getByRole('dialog', { name: '重绘图片' })).toBeTruthy();
+    });
+    expect(screen.getByAltText(/画布图片：生成图片 .* 重绘/)).toBeTruthy();
+    fireEvent.click(
+      screen.getAllByRole('button', {
+        name: /查看生成图片 .* 重绘图片信息/u,
+      })[0]!,
+    );
+    const editedMetadataDialog = screen.getByRole('dialog', {
+      name: '图片信息',
+    });
+    expect(within(editedMetadataDialog).queryByText('Prompt')).toBeNull();
+    expect(within(editedMetadataDialog).getByText('重绘提示词')).toBeTruthy();
+    expect(
+      within(editedMetadataDialog).getByText('把画面改成黄昏光线'),
+    ).toBeTruthy();
+    expect(within(editedMetadataDialog).getByText('参考图')).toBeTruthy();
+    expect(
+      within(editedMetadataDialog).getByText(/^生成图片 \d+$/u),
+    ).toBeTruthy();
+    expect(
+      screen.getByRole('button', { name: /当前缩放比例 \d+%/u }),
+    ).toBeTruthy();
+  });
+
+  it('keeps the redraw panel open after generation starts while keeping the source preview visible', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-edit-generating',
+      title: '重绘生成中画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-edit-generating-source',
+          resourceId: 'resource-edit-generating-source',
+          title: '待重绘',
+          src: 'data:image/png;base64,ZWRpdC1nZW5lcmF0aW5n',
+          x: 120,
+          y: 140,
+          width: 320,
+          height: 240,
+          originalWidth: 1024,
+          originalHeight: 768,
+          zIndex: 2,
+          sourceType: 'generated',
+          prompt: '原始提示词',
+          actualPrompt: '原始提示词',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'edit-generating-source-task',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-16T00:00:00.000Z',
+    });
+    generateEditorImageMock.mockReturnValueOnce(new Promise(() => undefined));
+    render(<ImageCanvasEditorView />);
+
+    const sourceImage = await screen.findByAltText('画布图片：待重绘');
+    const sourceLayer = sourceImage.closest('button')!;
+    fireEvent.pointerDown(sourceLayer, {
+      button: 0,
+      pointerId: 171,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 171,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '改造' }));
+    const editDialog = screen.getByRole('dialog', { name: '重绘图片' });
+    fireEvent.change(within(editDialog).getByLabelText('重绘提示词'), {
+      target: { value: '改成雨夜灯光' },
+    });
+    fireEvent.click(within(editDialog).getByRole('button', { name: '生成' }));
+
+    expect(screen.getByRole('dialog', { name: '重绘图片' })).toBeTruthy();
+    expect(screen.getByAltText('画布图片：待重绘')).toBeTruthy();
+    expect(sourceLayer.className).not.toContain(
+      'image-canvas-editor__layer--generating',
+    );
+    expect(within(editDialog).getByRole('button', { name: '生成中' })).toBeTruthy();
+  });
+
+  it('hides the quick edit panel after generation starts while keeping the source preview visible', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-quick-edit-generating',
+      title: '快速编辑生成中画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-quick-edit-generating-source',
+          resourceId: 'resource-quick-edit-generating-source',
+          title: '快速编辑源图',
+          src: 'data:image/png;base64,cXVpY2stZWRpdC1nZW5lcmF0aW5n',
+          x: 120,
+          y: 140,
+          width: 320,
+          height: 240,
+          originalWidth: 1024,
+          originalHeight: 768,
+          zIndex: 2,
+          sourceType: 'uploaded',
+          model: 'gpt-image-2',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-16T00:00:00.000Z',
+    });
+    generateEditorImageMock.mockReturnValueOnce(new Promise(() => undefined));
+    render(<ImageCanvasEditorView />);
+
+    const sourceImage = await screen.findByAltText('画布图片：快速编辑源图');
+    const sourceLayer = sourceImage.closest('button')!;
+    fireEvent.pointerDown(sourceLayer, {
+      button: 0,
+      pointerId: 172,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 172,
+      clientX: 180,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑' }));
+    const quickPanel = screen.getByRole('dialog', { name: '快速编辑图片' });
+    fireEvent.change(within(quickPanel).getByLabelText('快速编辑提示词'), {
+      target: { value: '加一层暖光' },
+    });
+    fireEvent.click(within(quickPanel).getByRole('button', { name: '生成' }));
+
+    expect(screen.queryByRole('dialog', { name: '快速编辑图片' })).toBeNull();
+    expect(screen.getByAltText('画布图片：快速编辑源图')).toBeTruthy();
+    expect(sourceLayer.className).not.toContain(
+      'image-canvas-editor__layer--generating',
+    );
+    const quickEditFrame = screen.getByLabelText('快速编辑生成占位图');
+    expect(quickEditFrame).toBeTruthy();
+    expect(quickEditFrame.className).toContain(
+      'image-canvas-editor__generation-frame--generating',
+    );
+    expect(within(quickEditFrame).getByRole('status').textContent).toContain(
+      '生成中',
+    );
+
+    await act(async () => {
+      fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
+    });
+
+    const confirmDialog = screen.getByRole('dialog', {
+      name: '删除生成中的占位图',
+    });
+    expect(screen.getByLabelText('快速编辑生成占位图')).toBeTruthy();
+    fireEvent.click(within(confirmDialog).getByRole('button', { name: '确认删除' }));
+
+    expect(screen.queryByLabelText('快速编辑生成占位图')).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasEditorModel.test.ts b/src/components/image-editor/ImageCanvasEditorModel.test.ts
new file mode 100644
index 000000000..9841871d0
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorModel.test.ts
@@ -0,0 +1,667 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CANVAS_WORLD_ORIGIN,
+  createLayerFromAsset,
+  hydrateLayer,
+  normalizeAssetLibrary,
+  normalizeCanvasBackgroundHex,
+  resolveSnappedLayerPosition,
+  serializeCanvasLayout,
+  serializeLayer,
+  splitCanvasLayoutItems,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+
+describe('ImageCanvasEditorModel', () => {
+  it('normalizes valid canvas background hex values and rejects invalid input', () => {
+    expect(normalizeCanvasBackgroundHex(' #ABC ')).toBe('#aabbcc');
+    expect(normalizeCanvasBackgroundHex('#f8fafc')).toBe('#f8fafc');
+    expect(normalizeCanvasBackgroundHex('white')).toBeNull();
+    expect(normalizeCanvasBackgroundHex('#not-a-color')).toBeNull();
+  });
+
+  it('keeps only one default asset folder when normalizing the persisted library', () => {
+    const library = normalizeAssetLibrary({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'project-duplicate',
+          label: '旧项目素材',
+          sortOrder: 1,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+
+    expect(library.folders).toHaveLength(1);
+    expect(library.folders[0]?.id).toBe('project');
+  });
+
+  it('infers MP3 and MP4 asset media types from persisted paths', () => {
+    const library = normalizeAssetLibrary({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-audio',
+          folderId: 'project',
+          label: '胜利音效.mp3',
+          imageSrc: '/generated-character-drafts/editor/asset-library/audio/胜利音效.mp3',
+          width: 420,
+          height: 120,
+          sourceType: 'uploaded',
+          objectKey:
+            'generated-character-drafts/editor/asset-library/audio/胜利音效.mp3',
+        },
+        {
+          assetId: 'asset-video',
+          folderId: 'project',
+          label: '开场动画.mp4',
+          imageSrc: '/generated-character-drafts/editor/asset-library/video/开场动画.mp4',
+          width: 560,
+          height: 315,
+          sourceType: 'uploaded',
+          objectKey:
+            'generated-character-drafts/editor/asset-library/video/开场动画.mp4',
+        },
+      ],
+    });
+
+    expect(library.assets[0]).toMatchObject({ mediaType: 'audio' });
+    expect(library.assets[1]).toMatchObject({ mediaType: 'video' });
+    expect(
+      createLayerFromAsset(
+        library.assets[0]!,
+        1,
+        { x: 0, y: 0, scale: 1 },
+        { x: 300, y: 200 },
+      ),
+    ).toMatchObject({
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+    });
+  });
+
+  it('creates a layer from an account asset at the requested screen point', () => {
+    const asset: EditorAsset = {
+      id: 'asset-1',
+      label: '角色草图',
+      src: 'data:image/png;base64,one',
+      width: 640,
+      height: 480,
+      folderId: 'project',
+      sourceKind: 'uploaded',
+      sourceType: 'uploaded',
+      persisted: true,
+      objectKey: 'oss/asset-1.png',
+      assetObjectId: 'object-1',
+    };
+
+    const layer = createLayerFromAsset(
+      asset,
+      3,
+      { x: 20, y: 40, scale: 2 },
+      { x: 420, y: 340 },
+    );
+
+    expect(layer).toMatchObject({
+      id: 'layer-asset-1-3',
+      title: '角色草图',
+      width: 640,
+      height: 480,
+      originalWidth: 640,
+      originalHeight: 480,
+      objectKey: 'oss/asset-1.png',
+      assetObjectId: 'object-1',
+      sourceAssetId: 'asset-1',
+    });
+    expect(layer.x).toBe(-18);
+    expect(layer.y).toBe(12);
+  });
+
+  it('serializes and hydrates canvas layer metadata without embedding image payloads', () => {
+    const layer: CanvasLayer = {
+      id: 'layer-generated',
+      resourceId: 'resource-generated',
+      title: '生成图',
+      src: 'data:image/png;base64,heavy',
+      x: 10,
+      y: 20,
+      width: 1024,
+      height: 768,
+      originalWidth: 1024,
+      originalHeight: 768,
+      zIndex: 9,
+      sourceType: 'generated',
+      objectKey: 'generated/object.png',
+      assetKind: 'character',
+      generationInputs: {
+        fields: [{ title: '角色设定', value: '骑士' }],
+        references: [],
+      },
+      locked: true,
+    };
+
+    const snapshot = serializeLayer(layer);
+    expect(snapshot).not.toHaveProperty('src');
+    expect(snapshot).not.toHaveProperty('assetKind');
+    expect(snapshot).not.toHaveProperty('generationInputs');
+
+    const hydrated = hydrateLayer(
+      snapshot,
+      new Map([
+        [
+          'resource-generated',
+          {
+            imageSrc: '/read/generated.png',
+            assetKind: 'character',
+            generationInputs: {
+              fields: [{ title: '角色设定', value: '骑士' }],
+              references: [],
+            },
+          },
+        ],
+      ]),
+    );
+
+    expect(hydrated).toMatchObject({
+      id: 'layer-generated',
+      src: '/read/generated.png',
+      sourceType: 'generated',
+      assetKind: 'character',
+      objectKey: 'generated/object.png',
+      locked: true,
+    });
+    expect(hydrated?.generationInputs?.fields[0]?.value).toBe('骑士');
+  });
+
+  it('hydrates object metadata from project resources when the saved layer is lean', () => {
+    const hydrated = hydrateLayer(
+      {
+        layerId: 'layer-uploaded',
+        resourceId: 'resource-uploaded',
+        title: '上传图',
+        x: 10,
+        y: 20,
+        width: 640,
+        height: 360,
+        originalWidth: 640,
+        originalHeight: 360,
+        zIndex: 2,
+        sourceType: 'uploaded',
+      },
+      new Map([
+        [
+          'resource-uploaded',
+          {
+            imageSrc: '/generated-character-drafts/editor/asset-library/image.png',
+            objectKey: 'generated-character-drafts/editor/asset-library/image.png',
+            assetObjectId: 'asset-object-uploaded',
+            sourceResourceId: 'resource-source',
+          },
+        ],
+      ]),
+    );
+
+    expect(hydrated).toMatchObject({
+      id: 'layer-uploaded',
+      src: '/generated-character-drafts/editor/asset-library/image.png',
+      objectKey: 'generated-character-drafts/editor/asset-library/image.png',
+      assetObjectId: 'asset-object-uploaded',
+      sourceResourceId: 'resource-source',
+    });
+  });
+
+  it('hydrates manually selected publication material tags from saved layout', () => {
+    const hydrated = hydrateLayer(
+      {
+        layerId: 'layer-publication',
+        resourceId: 'resource-publication',
+        title: '宣发图',
+        x: 10,
+        y: 20,
+        width: 1024,
+        height: 1024,
+        originalWidth: 1024,
+        originalHeight: 1024,
+        zIndex: 5,
+        sourceType: 'generated',
+        assetKind: 'publication-material',
+      },
+      new Map([['resource-publication', { imageSrc: '/read/publication.png' }]]),
+    );
+
+    expect(hydrated).toMatchObject({
+      id: 'layer-publication',
+      assetKind: 'publication-material',
+    });
+  });
+
+  it('hydrates audio media type and sound effect asset kind from saved layout', () => {
+    const hydrated = hydrateLayer(
+      {
+        layerId: 'layer-audio',
+        resourceId: 'resource-audio',
+        title: '游戏音效',
+        x: 10,
+        y: 20,
+        width: 420,
+        height: 120,
+        originalWidth: 420,
+        originalHeight: 120,
+        zIndex: 5,
+        sourceType: 'generated',
+        mediaType: 'audio',
+        assetKind: 'sound-effect',
+        durationSeconds: 2.4,
+      },
+      new Map([
+        [
+          'resource-audio',
+          {
+            imageSrc: '/generated-character-drafts/editor-audios/sfx.mp3',
+            durationSeconds: 2.4,
+          },
+        ],
+      ]),
+    );
+
+    expect(hydrated).toMatchObject({
+      id: 'layer-audio',
+      src: '/generated-character-drafts/editor-audios/sfx.mp3',
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+      durationSeconds: 2.4,
+    });
+  });
+
+  it('serializes and hydrates video thumbnails for character animation layers', () => {
+    const layer: CanvasLayer = {
+      id: 'layer-action',
+      resourceId: 'resource-action',
+      title: '角色动作',
+      src: '/generated-character-drafts/editor/preview.mp4',
+      mediaType: 'video',
+      thumbnailSrc: '/generated-character-drafts/editor/frame01.png',
+      x: 10,
+      y: 20,
+      width: 420,
+      height: 420,
+      originalWidth: 1024,
+      originalHeight: 1024,
+      zIndex: 6,
+      sourceType: 'generated',
+      assetKind: 'character-animation',
+      durationSeconds: 4,
+    };
+
+    const snapshot = serializeLayer(layer);
+    expect(snapshot.thumbnailSrc).toBe(
+      '/generated-character-drafts/editor/frame01.png',
+    );
+
+    const hydrated = hydrateLayer(
+      snapshot,
+      new Map([
+        [
+          'resource-action',
+          {
+            imageSrc: layer.src,
+            assetKind: 'character-animation',
+          },
+        ],
+      ]),
+    );
+
+    expect(hydrated).toMatchObject({
+      mediaType: 'video',
+      thumbnailSrc: '/generated-character-drafts/editor/frame01.png',
+      assetKind: 'character-animation',
+      durationSeconds: 4,
+    });
+  });
+
+  it('restores audio generation dialogs from saved layout', () => {
+    const dialog: CanvasGenerationDialogState = {
+      id: 'generation-dialog-audio',
+      mode: 'audio-sound-effect',
+      prompt: '金币掉落叮当声',
+      status: 'idle',
+      composerOpen: true,
+      soundDurationSeconds: 8,
+      generatedLayerId: 'layer-audio',
+      placeholder: {
+        x: 100,
+        y: 120,
+        width: 420,
+        height: 120,
+        originalWidth: 420,
+        originalHeight: 120,
+      },
+    };
+
+    const { generationDialogs } = splitCanvasLayoutItems(
+      serializeCanvasLayout({
+        layers: [],
+        canvasGenerationDialogs: [dialog],
+      }),
+    );
+
+    expect(generationDialogs).toHaveLength(1);
+    expect(generationDialogs[0]).toMatchObject({
+      id: 'generation-dialog-audio',
+      mode: 'audio-sound-effect',
+      prompt: '金币掉落叮当声',
+      soundDurationSeconds: 8,
+      generatedLayerId: 'layer-audio',
+    });
+  });
+
+  it('restores publication material generator inputs from saved layout', () => {
+    const dialog: CanvasGenerationDialogState = {
+      id: 'generation-dialog-publication',
+      mode: 'publication',
+      prompt: '马戏团午夜惊魂｜非对称对抗｜找到钥匙逃离',
+      status: 'idle',
+      composerOpen: true,
+      publicationWorkflowId: 'publication-promo-poster',
+      publicationGameInfo: {
+        gameName: '马戏团午夜惊魂',
+        gameCategories: '非对称对抗',
+        gameDescription: '找到钥匙，开门逃离马戏团',
+      },
+      publicationReferences: [
+        {
+          id: 'publication-reference-1',
+          label: '首图参考',
+          src: 'data:image/png;base64,publication-ref',
+          resourceId: 'resource-publication-reference',
+        },
+      ],
+      imageModel: 'gpt-image-2',
+      aspectRatio: '16:9',
+      imageSize: '2K',
+      generatedLayerId: 'layer-publication',
+      placeholder: {
+        x: 100,
+        y: 120,
+        width: 1280,
+        height: 720,
+        originalWidth: 1280,
+        originalHeight: 720,
+      },
+    };
+
+    const layout = serializeCanvasLayout({
+      layers: [],
+      canvasGenerationDialogs: [dialog],
+    });
+    expect(JSON.stringify(layout)).not.toContain('data:image');
+    expect(JSON.stringify(layout)).toContain(
+      'ref:project-resource:resource-publication-reference',
+    );
+
+    const { generationDialogs } = splitCanvasLayoutItems(
+      layout,
+      new Map([
+        [
+          'resource-publication-reference',
+          {
+            imageSrc: '/read/publication-reference.png',
+            objectKey: 'generated-character-drafts/editor/reference.png',
+            assetObjectId: 'asset-object-publication-reference',
+          },
+        ],
+      ]),
+    );
+
+    expect(generationDialogs).toHaveLength(1);
+    expect(generationDialogs[0]).toMatchObject({
+      id: 'generation-dialog-publication',
+      mode: 'publication',
+      publicationWorkflowId: 'publication-promo-poster',
+      publicationGameInfo: {
+        gameName: '马戏团午夜惊魂',
+        gameCategories: '非对称对抗',
+        gameDescription: '找到钥匙，开门逃离马戏团',
+      },
+      imageModel: 'gpt-image-2',
+      generatedLayerId: 'layer-publication',
+    });
+    expect(generationDialogs[0]?.publicationReferences?.[0]).toMatchObject({
+      id: 'publication-reference-1',
+      label: '首图参考',
+      src: '/read/publication-reference.png',
+      objectKey: 'generated-character-drafts/editor/reference.png',
+      assetObjectId: 'asset-object-publication-reference',
+      resourceId: 'resource-publication-reference',
+    });
+  });
+
+  it('serializes generation dialogs beside layers and splits them on load', () => {
+    const layer: CanvasLayer = {
+      id: 'layer-generated',
+      resourceId: 'resource-generated',
+      title: '生成图',
+      src: 'data:image/png;base64,heavy',
+      x: 10,
+      y: 20,
+      width: 1024,
+      height: 768,
+      originalWidth: 1024,
+      originalHeight: 768,
+      zIndex: 9,
+      sourceType: 'generated',
+    };
+    const dialog: CanvasGenerationDialogState = {
+      id: 'generation-dialog-9',
+      mode: 'generate',
+      prompt: '刷新后要继续保留',
+      status: 'generating',
+      composerOpen: false,
+      generatedLayerId: 'layer-generated',
+      imageModel: 'gpt-image-2',
+      placeholder: {
+        x: 100,
+        y: 120,
+        width: 420,
+        height: 420,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+      generationReferences: [
+        {
+          id: 'reference-1',
+          label: '参考图',
+          src: 'data:image/png;base64,ref',
+          resourceId: 'resource-reference-1',
+        },
+      ],
+    };
+
+    const layout = serializeCanvasLayout({
+      layers: [layer],
+      canvasGenerationDialogs: [dialog],
+    });
+    expect(
+      JSON.stringify(
+        layout.find((item) => item.resourceId === 'generation-dialog:generation-dialog-9'),
+      ),
+    ).not.toContain('data:image');
+    expect(
+      JSON.stringify(
+        layout.find((item) => item.resourceId === 'generation-dialog:generation-dialog-9'),
+      ),
+    ).toContain('ref:project-resource:resource-reference-1');
+
+    const { layerItems, generationDialogs } = splitCanvasLayoutItems(
+      layout,
+      new Map([
+        [
+          'resource-reference-1',
+          {
+            imageSrc: '/read/reference-1.png',
+            objectKey: 'generated/reference-1.png',
+          },
+        ],
+      ]),
+    );
+
+    expect(layerItems).toHaveLength(1);
+    expect(generationDialogs).toHaveLength(1);
+    expect(generationDialogs[0]).toMatchObject({
+      id: 'generation-dialog-9',
+      mode: 'generate',
+      prompt: '刷新后要继续保留',
+      status: 'generating',
+      generatedLayerId: 'layer-generated',
+      imageModel: 'gpt-image-2',
+      placeholder: {
+        x: 100,
+        y: 120,
+        width: 420,
+      },
+    });
+    expect(generationDialogs[0]?.generationReferences?.[0]).toMatchObject({
+      label: '参考图',
+      src: '/read/reference-1.png',
+      resourceId: 'resource-reference-1',
+      objectKey: 'generated/reference-1.png',
+    });
+  });
+
+  it('snaps moving layers to nearby canvas and layer guides', () => {
+    const movingLayer: CanvasLayer = {
+      id: 'moving',
+      resourceId: 'resource-moving',
+      title: '移动图',
+      src: 'data:image/png;base64,moving',
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      originalWidth: 100,
+      originalHeight: 100,
+      zIndex: 1,
+      sourceType: 'uploaded',
+    };
+    const anchorLayer: CanvasLayer = {
+      ...movingLayer,
+      id: 'anchor',
+      resourceId: 'resource-anchor',
+      x: 300,
+      y: 240,
+      zIndex: 2,
+    };
+
+    const snapped = resolveSnappedLayerPosition(
+      movingLayer,
+      CANVAS_WORLD_ORIGIN - 47,
+      238,
+      [movingLayer, anchorLayer],
+      1,
+    );
+
+    expect(snapped.x).toBe(CANVAS_WORLD_ORIGIN - movingLayer.width / 2);
+    expect(snapped.y).toBe(anchorLayer.y);
+    expect(snapped.guide).toEqual({
+      vertical: CANVAS_WORLD_ORIGIN,
+      horizontal: anchorLayer.y,
+    });
+  });
+
+  it('snaps moving layers to equal horizontal and vertical spacing', () => {
+    const movingLayer: CanvasLayer = {
+      id: 'moving',
+      resourceId: 'resource-moving',
+      title: '移动图',
+      src: 'data:image/png;base64,moving',
+      x: 0,
+      y: 0,
+      width: 80,
+      height: 80,
+      originalWidth: 80,
+      originalHeight: 80,
+      zIndex: 1,
+      sourceType: 'uploaded',
+    };
+    const firstLayer: CanvasLayer = {
+      ...movingLayer,
+      id: 'first',
+      resourceId: 'resource-first',
+      x: 100,
+      y: 160,
+      zIndex: 2,
+    };
+    const secondLayer: CanvasLayer = {
+      ...movingLayer,
+      id: 'second',
+      resourceId: 'resource-second',
+      x: 260,
+      y: 160,
+      zIndex: 3,
+    };
+    const topLayer: CanvasLayer = {
+      ...movingLayer,
+      id: 'top',
+      resourceId: 'resource-top',
+      x: 520,
+      y: 120,
+      zIndex: 4,
+    };
+    const bottomLayer: CanvasLayer = {
+      ...movingLayer,
+      id: 'bottom',
+      resourceId: 'resource-bottom',
+      x: 520,
+      y: 300,
+      zIndex: 5,
+    };
+
+    const horizontalSnap = resolveSnappedLayerPosition(
+      movingLayer,
+      417,
+      160,
+      [movingLayer, firstLayer, secondLayer],
+      1,
+    );
+    expect(horizontalSnap.x).toBe(420);
+    expect(horizontalSnap.guide).toEqual({
+      vertical: 460,
+      horizontal: 160,
+    });
+
+    const verticalSnap = resolveSnappedLayerPosition(
+      movingLayer,
+      520,
+      207,
+      [movingLayer, topLayer, bottomLayer],
+      1,
+    );
+    expect(verticalSnap.y).toBe(210);
+    expect(verticalSnap.guide).toEqual({
+      vertical: 520,
+      horizontal: 250,
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasEditorModel.ts b/src/components/image-editor/ImageCanvasEditorModel.ts
new file mode 100644
index 000000000..359e54825
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorModel.ts
@@ -0,0 +1,1371 @@
+import type {
+  EditorAssetLibrarySnapshot,
+  EditorCharacterAnimationGenerationResult,
+  EditorProjectLayerSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import type {
+  CanvasAssetKind,
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasGenerationInputs,
+  CanvasLayer,
+  CanvasSnapItem,
+  CanvasMediaType,
+  CanvasViewport,
+  CharacterReferenceImage,
+  EditorAsset,
+  EditorAssetFolder,
+  SnapCandidate,
+} from './ImageCanvasEditorTypes';
+
+export const EDITOR_ASSET_FOLDERS: EditorAssetFolder[] = [
+  {
+    id: 'project',
+    label: '项目素材',
+    collapsed: false,
+    systemDefault: true,
+    persisted: false,
+  },
+];
+
+export const CANVAS_WORLD_SIZE = 12000;
+export const CANVAS_WORLD_ORIGIN = CANVAS_WORLD_SIZE / 2;
+export const MIN_SCALE = 0.24;
+export const MAX_SCALE = 3.2;
+export const TOOLBAR_HALF_WIDTH = 132;
+export const DEFAULT_CANVAS_SIZE = { width: 900, height: 640 };
+export const SNAP_THRESHOLD_SCREEN_PX = 18;
+export const SNAP_DISTRIBUTION_OVERLAP_TOLERANCE = 1;
+export const FIT_VIEW_PADDING = 10;
+export const MINIMAP_SIZE = { width: 132, height: 84 };
+export const MINIMAP_PADDING = 8;
+export const MINIMAP_DRAG_SENSITIVITY = 0.3;
+export const ASSET_DRAG_MIME_TYPE = 'application/x-genarrative-editor-asset';
+export const MAX_HISTORY_STEPS = 60;
+export const CONTEXT_MENU_VIEWPORT_MARGIN = 8;
+export const CONTEXT_MENU_SIZE = {
+  blank: { width: 188, height: 176 },
+  layer: { width: 188, height: 492 },
+} as const;
+export const CANVAS_BACKGROUND_OPTIONS = [
+  { label: '白色', value: '#ffffff' },
+  { label: '浅灰', value: '#f8fafc' },
+  { label: '暖灰', value: '#f3f0ea' },
+  { label: '冷蓝', value: '#eef6ff' },
+];
+export const DEFAULT_CANVAS_BACKGROUND_COLOR = '#f8fafc';
+
+export function normalizeCanvasBackgroundHex(value: string) {
+  const trimmedValue = value.trim().toLowerCase();
+  const match = /^#([0-9a-f]{3}|[0-9a-f]{6})$/u.exec(trimmedValue);
+  if (!match) {
+    return null;
+  }
+  const hexValue = match[1] ?? '';
+  if (hexValue.length === 3) {
+    return `#${hexValue
+      .split('')
+      .map((part) => `${part}${part}`)
+      .join('')}`;
+  }
+  return `#${hexValue}`;
+}
+
+export function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function formatPercent(value: number) {
+  return `${Math.round(value * 100)}%`;
+}
+
+export function formatImageSizeValue(width: number, height: number) {
+  const safeWidth = Math.max(1, Math.round(width || 1024));
+  const safeHeight = Math.max(1, Math.round(height || 1024));
+  return `${safeWidth}x${safeHeight}`;
+}
+
+export function resolveLayerResolutionSize(
+  originalWidth: number,
+  originalHeight: number,
+  fallback: { width: number; height: number },
+) {
+  // 中文注释：画布不再维护独立展示 Size，图片显示尺寸统一跟随图片原始 Resolution。
+  return {
+    width: Math.max(1, Math.round(originalWidth || fallback.width || 1)),
+    height: Math.max(1, Math.round(originalHeight || fallback.height || 1)),
+  };
+}
+
+export function createLayerFromAsset(
+  asset: EditorAsset,
+  index: number,
+  viewport: CanvasViewport,
+  screenCenter: { x: number; y: number },
+): CanvasLayer {
+  const { width, height } = resolveLayerResolutionSize(
+    asset.width,
+    asset.height,
+    { width: 360, height: 360 },
+  );
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  const safeScreenCenter = {
+    x: Number.isFinite(screenCenter.x) ? screenCenter.x : 0,
+    y: Number.isFinite(screenCenter.y) ? screenCenter.y : 0,
+  };
+  const worldCenterX = (safeScreenCenter.x - viewport.x) / safeScale;
+  const worldCenterY = (safeScreenCenter.y - viewport.y) / safeScale;
+  const offset = index * 34;
+  const assetKind: CanvasAssetKind | undefined =
+    asset.mediaType === 'video'
+      ? 'video'
+      : asset.mediaType === 'audio'
+        ? inferAudioAssetKindFromLabel(asset.label)
+        : undefined;
+
+  return {
+    id: `layer-${asset.id}-${index}`,
+    resourceId: `local-resource-${asset.id}-${index}`,
+    title: asset.label,
+    src: asset.src,
+    mediaType: asset.mediaType,
+    x: worldCenterX - width / 2 + offset,
+    y: worldCenterY - height / 2 + offset,
+    width,
+    height,
+    originalWidth: asset.width,
+    originalHeight: asset.height,
+    zIndex: index + 10,
+    sourceType: asset.sourceType,
+    prompt: asset.prompt,
+    actualPrompt: asset.actualPrompt,
+    model: asset.model,
+    provider: asset.provider,
+    taskId: asset.taskId,
+    objectKey: asset.objectKey,
+    assetObjectId: asset.assetObjectId,
+    durationSeconds: asset.durationSeconds,
+    sourceAssetId: asset.id,
+    assetKind: asset.assetKind ?? assetKind,
+    generationInputs: asset.generationInputs,
+  } satisfies CanvasLayer;
+}
+
+export function serializeLayer(
+  layer: CanvasLayer,
+): EditorProjectLayerSnapshot {
+  return {
+    layerId: layer.id,
+    resourceId: layer.resourceId,
+    title: layer.title,
+    x: layer.x,
+    y: layer.y,
+    width: layer.width,
+    height: layer.height,
+    originalWidth: layer.originalWidth,
+    originalHeight: layer.originalHeight,
+    zIndex: layer.zIndex,
+    sourceType: layer.sourceType,
+    mediaType: layer.mediaType,
+    thumbnailSrc: layer.thumbnailSrc,
+    prompt: layer.prompt,
+    actualPrompt: layer.actualPrompt,
+    model: layer.model,
+    provider: layer.provider,
+    taskId: layer.taskId,
+    objectKey: layer.objectKey,
+    assetObjectId: layer.assetObjectId,
+    durationSeconds: layer.durationSeconds,
+    sourceResourceId: layer.sourceResourceId,
+    sourceAssetId: layer.sourceAssetId,
+    groupId: layer.groupId,
+    hidden: layer.hidden,
+    locked: layer.locked,
+    flipX: layer.flipX,
+    flipY: layer.flipY,
+  };
+}
+
+type CanvasGenerationDialogSnapshot = EditorProjectLayerSnapshot & {
+  itemType: 'generation-dialog';
+  dialog: CanvasGenerationDialogState;
+};
+
+export type CanvasLayoutItems = EditorProjectLayerSnapshot[];
+
+function isPersistedReferenceResourceId(resourceId: string | null | undefined) {
+  const normalizedResourceId = resourceId?.trim();
+  return Boolean(
+    normalizedResourceId &&
+      !normalizedResourceId.startsWith('local-') &&
+      !normalizedResourceId.startsWith('generation-dialog:'),
+  );
+}
+
+function isPersistedReferenceAssetId(assetId: string | null | undefined) {
+  const normalizedAssetId = assetId?.trim();
+  return Boolean(normalizedAssetId && !normalizedAssetId.startsWith('upload-'));
+}
+
+function resolveReferencePointer(reference: CharacterReferenceImage) {
+  const resourceId = reference.resourceId?.trim();
+  if (isPersistedReferenceResourceId(resourceId)) {
+    return {
+      src: `ref:project-resource:${resourceId}`,
+      resourceId,
+      sourceAssetId: reference.sourceAssetId,
+    };
+  }
+  const sourceAssetId = reference.sourceAssetId?.trim();
+  if (isPersistedReferenceAssetId(sourceAssetId)) {
+    return {
+      src: `ref:asset:${sourceAssetId}`,
+      resourceId: reference.resourceId,
+      sourceAssetId,
+    };
+  }
+  return null;
+}
+
+function serializeGenerationReference(
+  reference: CharacterReferenceImage | null | undefined,
+): CharacterReferenceImage | null {
+  if (!reference) {
+    return null;
+  }
+  const pointer = resolveReferencePointer(reference);
+  if (!pointer) {
+    return null;
+  }
+  return {
+    id: reference.id,
+    label: reference.label,
+    src: pointer.src,
+    mediaType: reference.mediaType,
+    mimeType: reference.mimeType,
+    sizeBytes: reference.sizeBytes,
+    durationSeconds: reference.durationSeconds,
+    resourceId: pointer.resourceId,
+    sourceAssetId: pointer.sourceAssetId,
+  };
+}
+
+function serializeGenerationReferences(
+  references: CharacterReferenceImage[] | undefined,
+) {
+  if (!references) {
+    return undefined;
+  }
+  return references.flatMap((reference) => {
+    const serialized = serializeGenerationReference(reference);
+    return serialized ? [serialized] : [];
+  });
+}
+
+function serializeDialogReferences(
+  dialog: CanvasGenerationDialogState,
+): CanvasGenerationDialogState {
+  return {
+    ...dialog,
+    specReference: serializeGenerationReference(dialog.specReference),
+    generationReferences: serializeGenerationReferences(
+      dialog.generationReferences,
+    ),
+    characterSpecReference: serializeGenerationReference(
+      dialog.characterSpecReference,
+    ),
+    characterReferences: serializeGenerationReferences(
+      dialog.characterReferences,
+    ),
+    iconSpecReference: serializeGenerationReference(dialog.iconSpecReference),
+    publicationReferences: serializeGenerationReferences(
+      dialog.publicationReferences,
+    ),
+    uiDesignSpecReference: serializeGenerationReference(
+      dialog.uiDesignSpecReference,
+    ),
+  };
+}
+
+export function serializeCanvasGenerationDialog(
+  dialog: CanvasGenerationDialogState,
+): CanvasGenerationDialogSnapshot {
+  return {
+    itemType: 'generation-dialog',
+    layerId: `generation-dialog:${dialog.id}`,
+    resourceId: `generation-dialog:${dialog.id}`,
+    dialog: serializeDialogReferences(dialog),
+  };
+}
+
+export function serializeCanvasLayout({
+  layers,
+  canvasGenerationDialogs,
+}: {
+  layers: CanvasLayer[];
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+}): CanvasLayoutItems {
+  return [
+    ...layers.map(serializeLayer),
+    ...canvasGenerationDialogs.map(serializeCanvasGenerationDialog),
+  ];
+}
+
+export function isCanvasGenerationDialogLayoutItem(
+  item: EditorProjectLayerSnapshot,
+): item is CanvasGenerationDialogSnapshot {
+  return (
+    item.itemType === 'generation-dialog' &&
+    Boolean(
+      hydrateCanvasGenerationDialog(
+        (item as { dialog?: unknown }).dialog,
+      ),
+    )
+  );
+}
+
+export function splitCanvasLayoutItems(
+  items: EditorProjectLayerSnapshot[],
+  resourcesById: Map<string, CanvasLayerResourceMetadata> = new Map(),
+): {
+  layerItems: EditorProjectLayerSnapshot[];
+  generationDialogs: CanvasGenerationDialogState[];
+} {
+  const layerItems: EditorProjectLayerSnapshot[] = [];
+  const generationDialogs: CanvasGenerationDialogState[] = [];
+
+  items.forEach((item) => {
+    if (isCanvasGenerationDialogLayoutItem(item)) {
+      const dialog = hydrateCanvasGenerationDialog(item.dialog, resourcesById);
+      if (dialog) {
+        generationDialogs.push(dialog);
+      }
+      return;
+    }
+    layerItems.push(item);
+  });
+
+  return { layerItems, generationDialogs };
+}
+
+export function hydrateCanvasGenerationDialog(
+  value: unknown,
+  resourcesById: Map<string, CanvasLayerResourceMetadata> = new Map(),
+): CanvasGenerationDialogState | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const snapshot = value as Partial<CanvasGenerationDialogState>;
+  const id = stringOrNull(snapshot.id);
+  const prompt = typeof snapshot.prompt === 'string' ? snapshot.prompt : '';
+  if (!id || !isCanvasGenerationDialogMode(snapshot.mode)) {
+    return null;
+  }
+
+  return {
+    id,
+    mode: snapshot.mode,
+    prompt,
+    status: isGenerationStatus(snapshot.status) ? snapshot.status : 'idle',
+    composerOpen:
+      typeof snapshot.composerOpen === 'boolean'
+        ? snapshot.composerOpen
+        : true,
+    sourceLayerId: stringOrUndefined(snapshot.sourceLayerId),
+    generatedLayerId: stringOrUndefined(snapshot.generatedLayerId),
+    specType: isSpecGenerationType(snapshot.specType)
+      ? snapshot.specType
+      : undefined,
+    specValues: hydrateSpecFormValues(snapshot.specValues),
+    specReference: hydrateCharacterReference(
+      snapshot.specReference,
+      resourcesById,
+    ),
+    generationReferences: hydrateCharacterReferences(
+      snapshot.generationReferences,
+      resourcesById,
+    ),
+    characterSpecReference: hydrateCharacterReference(
+      snapshot.characterSpecReference,
+      resourcesById,
+    ),
+    characterReferences: hydrateCharacterReferences(
+      snapshot.characterReferences,
+      resourcesById,
+    ),
+    iconSpecReference: hydrateCharacterReference(
+      snapshot.iconSpecReference,
+      resourcesById,
+    ),
+    iconDescriptions: Array.isArray(snapshot.iconDescriptions)
+      ? snapshot.iconDescriptions.filter(
+          (description): description is string =>
+            typeof description === 'string',
+        )
+      : undefined,
+    publicationWorkflowId: hydratePublicationWorkflowId(
+      snapshot.publicationWorkflowId,
+    ),
+    publicationGameInfo: hydratePublicationGameInfo(
+      snapshot.publicationGameInfo,
+    ),
+    publicationReferences: hydrateCharacterReferences(
+      snapshot.publicationReferences,
+      resourcesById,
+    ),
+    uiDesignSpecReference: hydrateCharacterReference(
+      snapshot.uiDesignSpecReference,
+      resourcesById,
+    ),
+    imageModel: stringOrUndefined(snapshot.imageModel),
+    videoModel:
+      typeof snapshot.videoModel === 'string'
+        ? snapshot.videoModel
+        : undefined,
+    videoAspectRatio: videoAspectRatioOrUndefined(snapshot.videoAspectRatio),
+    videoResolution:
+      snapshot.videoResolution === '480p' ||
+      snapshot.videoResolution === '720p' ||
+      snapshot.videoResolution === '1080p'
+        ? snapshot.videoResolution
+        : undefined,
+    videoDurationSeconds:
+      typeof snapshot.videoDurationSeconds === 'number'
+        ? Math.min(15, Math.max(4, Math.round(snapshot.videoDurationSeconds)))
+        : undefined,
+    videoMode: snapshot.videoMode === 'std' ? 'std' : undefined,
+    videoSound:
+      snapshot.videoSound === 'on' || snapshot.videoSound === 'off'
+        ? snapshot.videoSound
+        : undefined,
+    videoWebSearchEnabled:
+      typeof snapshot.videoWebSearchEnabled === 'boolean'
+        ? snapshot.videoWebSearchEnabled
+        : undefined,
+    characterAnimationResolution:
+      snapshot.characterAnimationResolution === '480p' ||
+      snapshot.characterAnimationResolution === '720p'
+        ? snapshot.characterAnimationResolution
+        : undefined,
+    characterAnimationRatio:
+      snapshot.characterAnimationRatio === 'same' ||
+      snapshot.characterAnimationRatio === '1:1' ||
+      snapshot.characterAnimationRatio === '4:3' ||
+      snapshot.characterAnimationRatio === '16:9' ||
+      snapshot.characterAnimationRatio === '9:16' ||
+      snapshot.characterAnimationRatio === '3:4'
+        ? snapshot.characterAnimationRatio
+        : undefined,
+    characterAnimationFrameCount:
+      snapshot.characterAnimationFrameCount === 32 ||
+      snapshot.characterAnimationFrameCount === 40 ||
+      snapshot.characterAnimationFrameCount === 48
+        ? snapshot.characterAnimationFrameCount
+        : undefined,
+    characterAnimationDurationSeconds:
+      snapshot.characterAnimationDurationSeconds === 4 ||
+      snapshot.characterAnimationDurationSeconds === 5 ||
+      snapshot.characterAnimationDurationSeconds === 6
+        ? snapshot.characterAnimationDurationSeconds
+        : undefined,
+    characterAnimationResult: hydrateCharacterAnimationResult(
+      snapshot.characterAnimationResult,
+    ),
+    soundModel: snapshot.soundModel === 'audio1.0' ? 'audio1.0' : undefined,
+    soundDurationSeconds: soundDurationOrDefault(
+      snapshot.soundDurationSeconds,
+      snapshot.audioDurationSeconds,
+    ),
+    makeInstrumental:
+      typeof snapshot.makeInstrumental === 'boolean'
+        ? snapshot.makeInstrumental
+        : undefined,
+    audioDurationSeconds: audioDurationOrNull(snapshot.audioDurationSeconds),
+    aspectRatio: stringOrUndefined(snapshot.aspectRatio),
+    imageSize: stringOrUndefined(snapshot.imageSize),
+    errorMessage: stringOrUndefined(snapshot.errorMessage),
+    placeholder: hydrateGenerationPlaceholder(snapshot.placeholder),
+  };
+}
+
+export function hydrateLayer(
+  snapshot: EditorProjectLayerSnapshot,
+  resourcesById: Map<string, CanvasLayerResourceMetadata>,
+): CanvasLayer | null {
+  const resourceId =
+    typeof snapshot.resourceId === 'string' ? snapshot.resourceId : '';
+  const layerId = typeof snapshot.layerId === 'string' ? snapshot.layerId : '';
+  const resource = resourcesById.get(resourceId);
+  const snapshotSrc = typeof snapshot.src === 'string' ? snapshot.src : '';
+  const src = snapshotSrc || resource?.imageSrc || '';
+  const title =
+    typeof snapshot.title === 'string' ? snapshot.title : '画布图片';
+  if (!resourceId || !layerId || !src) {
+    return null;
+  }
+
+  return {
+    id: layerId,
+    resourceId,
+    title,
+    src,
+    x: numberFromSnapshot(snapshot.x, 0),
+    y: numberFromSnapshot(snapshot.y, 0),
+    ...(() => {
+      const originalWidth = numberFromSnapshot(snapshot.originalWidth, 320);
+      const originalHeight = numberFromSnapshot(snapshot.originalHeight, 320);
+      return {
+        ...resolveLayerResolutionSize(originalWidth, originalHeight, {
+          width: numberFromSnapshot(snapshot.width, 320),
+          height: numberFromSnapshot(snapshot.height, 320),
+        }),
+        originalWidth,
+        originalHeight,
+      };
+    })(),
+    zIndex: numberFromSnapshot(snapshot.zIndex, 1),
+    sourceType: isCanvasSourceType(snapshot.sourceType)
+      ? snapshot.sourceType
+      : 'uploaded',
+    mediaType:
+      snapshot.mediaType === 'video' || snapshot.mediaType === 'audio'
+        ? snapshot.mediaType
+        : 'image',
+    thumbnailSrc: stringOrNull(snapshot.thumbnailSrc),
+    prompt: stringOrNull(snapshot.prompt),
+    actualPrompt: stringOrNull(snapshot.actualPrompt),
+    model: stringOrNull(snapshot.model),
+    provider: stringOrNull(snapshot.provider),
+    taskId: stringOrNull(snapshot.taskId),
+    objectKey: stringOrNull(snapshot.objectKey) ?? stringOrNull(resource?.objectKey),
+    assetObjectId:
+      stringOrNull(snapshot.assetObjectId) ?? stringOrNull(resource?.assetObjectId),
+    durationSeconds:
+      audioDurationOrNull(snapshot.durationSeconds) ??
+      audioDurationOrNull(resource?.durationSeconds),
+    sourceResourceId:
+      stringOrNull(snapshot.sourceResourceId) ??
+      stringOrNull(resource?.sourceResourceId),
+    sourceAssetId: stringOrNull(snapshot.sourceAssetId),
+    groupId: stringOrNull(snapshot.groupId),
+    assetKind:
+      canvasAssetKindOrNull(resource?.assetKind) ??
+      canvasAssetKindOrNull(snapshot.assetKind),
+    generationInputs:
+      generationInputsOrNull(resource?.generationInputs) ??
+      generationInputsOrNull(snapshot.generationInputs),
+    hidden: booleanFromSnapshot(snapshot.hidden),
+    locked: booleanFromSnapshot(snapshot.locked),
+    flipX: booleanFromSnapshot(snapshot.flipX),
+    flipY: booleanFromSnapshot(snapshot.flipY),
+  };
+}
+
+export function mapAssetLibrarySnapshot(
+  library: EditorAssetLibrarySnapshot,
+): {
+  folders: EditorAssetFolder[];
+  assets: EditorAsset[];
+} {
+  return {
+    folders: library.folders.map((folder) => ({
+      id: folder.folderId,
+      label: folder.label,
+      collapsed: folder.collapsed,
+      systemDefault: folder.systemDefault,
+      persisted: true,
+    })),
+    assets: library.assets.map((asset) => {
+      const mediaType = inferEditorAssetMediaType(
+        asset.imageSrc,
+        asset.objectKey ?? undefined,
+      );
+      return {
+        id: asset.assetId,
+        label: asset.label,
+        src: asset.imageSrc,
+        mediaType,
+        width: asset.width,
+        height: asset.height,
+        folderId: asset.folderId,
+        sourceKind: 'uploaded',
+        sourceType: asset.sourceType,
+        persisted: true,
+        prompt: asset.prompt ?? undefined,
+        actualPrompt: asset.actualPrompt ?? undefined,
+        model: asset.model ?? undefined,
+        provider: asset.provider ?? undefined,
+        taskId: asset.taskId ?? undefined,
+        objectKey: asset.objectKey ?? undefined,
+        assetObjectId: asset.assetObjectId ?? undefined,
+        assetKind: canvasAssetKindOrNull(asset.assetKind),
+        generationInputs: generationInputsOrNull(asset.generationInputs),
+        durationSeconds: asset.durationSeconds ?? undefined,
+      };
+    }),
+  };
+}
+
+export function inferEditorAssetMediaType(
+  imageSrc: string,
+  objectKey?: string | null,
+): CanvasMediaType {
+  const source = `${objectKey ?? ''} ${imageSrc}`.toLowerCase();
+  const sourceWithoutQuery = source.split(/[?#]/u)[0] ?? source;
+  if (sourceWithoutQuery.includes('.mp4')) {
+    return 'video';
+  }
+  if (sourceWithoutQuery.includes('.mp3')) {
+    return 'audio';
+  }
+  return 'image';
+}
+
+function inferAudioAssetKindFromLabel(label: string): CanvasAssetKind {
+  return label.includes('背景音乐') || label.toLowerCase().includes('music')
+    ? 'background-music'
+    : 'sound-effect';
+}
+
+export type CanvasLayerResourceMetadata = {
+  resourceId?: string | null;
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width?: number | null;
+  height?: number | null;
+  sourceType?: string | null;
+  durationSeconds?: number | null;
+  sourceResourceId?: string | null;
+  assetKind?: string | null;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  generationInputs?: unknown;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+};
+
+export function normalizeAssetLibrary(library: EditorAssetLibrarySnapshot) {
+  const mapped = mapAssetLibrarySnapshot(library);
+  let hasDefaultFolder = false;
+  const normalizedFolders = mapped.folders.filter((folder) => {
+    if (!folder.systemDefault) {
+      return true;
+    }
+    if (hasDefaultFolder) {
+      return false;
+    }
+    hasDefaultFolder = true;
+    return true;
+  });
+  const persistedFolderIds = new Set(
+    normalizedFolders.map((folder) => folder.id),
+  );
+  const fallbackFolders = hasDefaultFolder
+    ? []
+    : EDITOR_ASSET_FOLDERS.filter(
+        (folder) => !persistedFolderIds.has(folder.id),
+      );
+  return {
+    folders: [...normalizedFolders, ...fallbackFolders],
+    assets: mapped.assets,
+  };
+}
+
+export function numberFromSnapshot(value: unknown, fallback: number) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function audioDurationOrNull(value: unknown) {
+  if (value && typeof value === 'object' && 'durationSeconds' in value) {
+    return audioDurationOrNull(
+      (value as { durationSeconds?: unknown }).durationSeconds,
+    );
+  }
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+export function bpmOrNull(value: unknown) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return undefined;
+  }
+  const roundedValue = Math.round(value);
+  return roundedValue >= 1 && roundedValue <= 300 ? roundedValue : undefined;
+}
+
+export function soundDurationOrDefault(
+  value: unknown,
+  fallbackValue?: unknown,
+) {
+  const resolvedValue = audioDurationOrNull(value) ?? audioDurationOrNull(fallbackValue);
+  if (!resolvedValue) {
+    return undefined;
+  }
+  return Math.min(10, Math.max(2, Math.round(resolvedValue)));
+}
+
+export function stringOrNull(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
+export function stringOrUndefined(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function videoAspectRatioOrUndefined(value: unknown) {
+  return value === '16:9' ||
+    value === '9:16' ||
+    value === '1:1' ||
+    value === '4:3' ||
+    value === '3:4' ||
+    value === '21:9'
+    ? value
+    : undefined;
+}
+
+function hydrateCharacterAnimationResult(
+  value: unknown,
+): EditorCharacterAnimationGenerationResult | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const result = value as Partial<EditorCharacterAnimationGenerationResult>;
+  if (
+    typeof result.taskId !== 'string' ||
+    result.model !== 'seedance2.0-fast' ||
+    typeof result.prompt !== 'string' ||
+    typeof result.previewVideoPath !== 'string' ||
+    !Array.isArray(result.frames) ||
+    typeof result.frameCount !== 'number' ||
+    typeof result.durationSeconds !== 'number' ||
+    typeof result.fps !== 'number' ||
+    typeof result.priceMudPoints !== 'number'
+  ) {
+    return undefined;
+  }
+  return result as EditorCharacterAnimationGenerationResult;
+}
+
+export function booleanFromSnapshot(value: unknown) {
+  return value === true;
+}
+
+export function resolveContextMenuPosition(
+  clientX: number,
+  clientY: number,
+  kind: CanvasContextMenuState['kind'],
+) {
+  if (typeof window === 'undefined') {
+    return { x: clientX, y: clientY };
+  }
+  const menuSize = CONTEXT_MENU_SIZE[kind];
+  return {
+    x: clamp(
+      clientX,
+      CONTEXT_MENU_VIEWPORT_MARGIN,
+      Math.max(
+        CONTEXT_MENU_VIEWPORT_MARGIN,
+        window.innerWidth - menuSize.width - CONTEXT_MENU_VIEWPORT_MARGIN,
+      ),
+    ),
+    y: clamp(
+      clientY,
+      CONTEXT_MENU_VIEWPORT_MARGIN,
+      Math.max(
+        CONTEXT_MENU_VIEWPORT_MARGIN,
+        window.innerHeight - menuSize.height - CONTEXT_MENU_VIEWPORT_MARGIN,
+      ),
+    ),
+  };
+}
+
+export function hasDataTransferType(
+  dataTransfer: DataTransfer,
+  type: string,
+) {
+  return Array.from(dataTransfer.types).includes(type);
+}
+
+export function getDraggedAssetId(dataTransfer: DataTransfer) {
+  if (typeof dataTransfer.getData !== 'function') {
+    return '';
+  }
+  if (!hasDataTransferType(dataTransfer, ASSET_DRAG_MIME_TYPE)) {
+    return '';
+  }
+  return dataTransfer.getData(ASSET_DRAG_MIME_TYPE);
+}
+
+export function escapeCssIdentifier(value: string) {
+  return typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+    ? CSS.escape(value)
+    : value.replace(/["\\]/gu, '\\$&');
+}
+
+export function isLayerLinkedToAsset(layer: CanvasLayer, asset: EditorAsset) {
+  return (
+    layer.sourceAssetId === asset.id ||
+    Boolean(asset.assetObjectId && layer.assetObjectId === asset.assetObjectId) ||
+    Boolean(asset.objectKey && layer.objectKey === asset.objectKey) ||
+    layer.src === asset.src
+  );
+}
+
+export function generationInputsOrNull(
+  value: unknown,
+): CanvasGenerationInputs | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const snapshot = value as {
+    fields?: unknown;
+    references?: unknown;
+  };
+  const fields = Array.isArray(snapshot.fields)
+    ? snapshot.fields.flatMap((field) => {
+        if (!field || typeof field !== 'object') {
+          return [];
+        }
+        const item = field as { title?: unknown; value?: unknown };
+        const title = stringOrNull(item.title);
+        const fieldValue = stringOrNull(item.value);
+        return title && fieldValue ? [{ title, value: fieldValue }] : [];
+      })
+    : [];
+  const references = Array.isArray(snapshot.references)
+    ? snapshot.references.flatMap((reference) => {
+        if (!reference || typeof reference !== 'object') {
+          return [];
+        }
+        const item = reference as {
+          title?: unknown;
+          label?: unknown;
+          refType?: unknown;
+          refId?: unknown;
+        };
+        const title = stringOrNull(item.title);
+        const label = stringOrNull(item.label);
+        const refType: 'project-resource' | 'asset' | null =
+          item.refType === 'project-resource' || item.refType === 'asset'
+            ? item.refType
+            : null;
+        const refId = stringOrNull(item.refId);
+        return title && label && refType && refId
+          ? [{ title, label, refType, refId }]
+          : [];
+      })
+    : [];
+
+  return fields.length || references.length ? { fields, references } : null;
+}
+
+export function canvasAssetKindOrNull(value: unknown): CanvasAssetKind | null {
+  return value === 'spec' ||
+    value === 'character' ||
+    value === 'character-animation' ||
+    value === 'icon' ||
+    value === 'icon-spritesheet' ||
+    value === 'icon-spec' ||
+    value === 'publication-material' ||
+    value === 'ui-design' ||
+    value === 'video' ||
+    value === 'sound-effect' ||
+    value === 'background-music'
+    ? value
+    : null;
+}
+
+export function isCanvasSourceType(
+  value: unknown,
+): value is CanvasLayer['sourceType'] {
+  return (
+    value === 'uploaded' || value === 'generated' || value === 'mock_generated'
+  );
+}
+
+export function isGeneratedLayer(layer: CanvasLayer) {
+  return (
+    layer.sourceType === 'generated' || layer.sourceType === 'mock_generated'
+  );
+}
+
+function isCanvasGenerationDialogMode(
+  value: unknown,
+): value is CanvasGenerationDialogState['mode'] {
+  return (
+    value === 'generate' ||
+    value === 'spec' ||
+    value === 'character' ||
+    value === 'icon' ||
+    value === 'publication' ||
+    value === 'ui-design' ||
+    value === 'quick-edit' ||
+    value === 'character-animation' ||
+    value === 'video' ||
+    value === 'audio-sound-effect' ||
+    value === 'audio-background-music'
+  );
+}
+
+function isGenerationStatus(
+  value: unknown,
+): value is CanvasGenerationDialogState['status'] {
+  return value === 'idle' || value === 'generating' || value === 'failed';
+}
+
+function isSpecGenerationType(
+  value: unknown,
+): value is NonNullable<CanvasGenerationDialogState['specType']> {
+  return (
+    value === 'character' ||
+    value === 'ui' ||
+    value === 'icon' ||
+    value === 'custom'
+  );
+}
+
+function hydratePublicationWorkflowId(
+  value: unknown,
+): CanvasGenerationDialogState['publicationWorkflowId'] {
+  return value === 'publication-cover-image' ||
+    value === 'publication-detail-gallery' ||
+    value === 'publication-promo-poster'
+    ? value
+    : undefined;
+}
+
+function hydratePublicationGameInfo(
+  value: unknown,
+): CanvasGenerationDialogState['publicationGameInfo'] {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const snapshot = value as Record<string, unknown>;
+  return {
+    gameName: stringOrUndefined(snapshot.gameName) ?? '',
+    gameCategories: stringOrUndefined(snapshot.gameCategories) ?? '',
+    gameDescription: stringOrUndefined(snapshot.gameDescription) ?? '',
+  };
+}
+
+function hydrateSpecFormValues(
+  value: unknown,
+): CanvasGenerationDialogState['specValues'] {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const snapshot = value as Record<string, unknown>;
+  return {
+    playSetting:
+      typeof snapshot.playSetting === 'string' ? snapshot.playSetting : '',
+    artStyle: typeof snapshot.artStyle === 'string' ? snapshot.artStyle : '',
+    bodyRatio: typeof snapshot.bodyRatio === 'string' ? snapshot.bodyRatio : '',
+    characterView:
+      typeof snapshot.characterView === 'string'
+        ? snapshot.characterView
+        : '',
+    customPrompt:
+      typeof snapshot.customPrompt === 'string' ? snapshot.customPrompt : '',
+  };
+}
+
+function resolveHydratedReferenceResource(
+  resourceId: string | undefined,
+  resourcesById: Map<string, CanvasLayerResourceMetadata>,
+) {
+  if (resourceId) {
+    return resourcesById.get(resourceId);
+  }
+  return undefined;
+}
+
+function hydrateCharacterReference(
+  value: unknown,
+  resourcesById: Map<string, CanvasLayerResourceMetadata> = new Map(),
+): CharacterReferenceImage | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const snapshot = value as Record<string, unknown>;
+  const id = stringOrNull(snapshot.id);
+  const label = stringOrNull(snapshot.label);
+  const src = stringOrNull(snapshot.src);
+  const resourceId = stringOrUndefined(snapshot.resourceId);
+  const sourceAssetId = stringOrUndefined(snapshot.sourceAssetId);
+  const mediaType: CanvasMediaType =
+    snapshot.mediaType === 'video' || snapshot.mediaType === 'audio'
+      ? snapshot.mediaType
+      : 'image';
+  const mimeType = stringOrUndefined(snapshot.mimeType);
+  const sizeBytes = numberFromSnapshot(snapshot.sizeBytes, 0) || undefined;
+  const durationSeconds =
+    numberFromSnapshot(snapshot.durationSeconds, 0) || undefined;
+  const resource = resolveHydratedReferenceResource(resourceId, resourcesById);
+  const objectKey =
+    stringOrUndefined(snapshot.objectKey) ?? stringOrUndefined(resource?.objectKey);
+  const assetObjectId =
+    stringOrUndefined(snapshot.assetObjectId) ??
+    stringOrUndefined(resource?.assetObjectId);
+  const resolvedSrc = resource?.imageSrc || objectKey || src;
+  return id && label && resolvedSrc
+    ? {
+        id,
+        label,
+        src: resolvedSrc,
+        mediaType,
+        mimeType,
+        sizeBytes,
+        durationSeconds,
+        objectKey,
+        assetObjectId,
+        resourceId,
+        sourceAssetId,
+      }
+    : null;
+}
+
+function hydrateCharacterReferences(
+  value: unknown,
+  resourcesById: Map<string, CanvasLayerResourceMetadata> = new Map(),
+): CharacterReferenceImage[] | undefined {
+  return Array.isArray(value)
+    ? value.flatMap((reference) => {
+        const hydrated = hydrateCharacterReference(reference, resourcesById);
+        return hydrated ? [hydrated] : [];
+      })
+    : undefined;
+}
+
+function hydrateGenerationPlaceholder(
+  value: unknown,
+): CanvasGenerationDialogState['placeholder'] {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const snapshot = value as Record<string, unknown>;
+  return {
+    x: numberFromSnapshot(snapshot.x, 0),
+    y: numberFromSnapshot(snapshot.y, 0),
+    width: numberFromSnapshot(snapshot.width, 320),
+    height: numberFromSnapshot(snapshot.height, 320),
+    originalWidth: numberFromSnapshot(snapshot.originalWidth, 320),
+    originalHeight: numberFromSnapshot(snapshot.originalHeight, 320),
+  };
+}
+
+export function getLayerBounds(targetLayers: CanvasLayer[]) {
+  if (targetLayers.length === 0) {
+    return null;
+  }
+
+  return targetLayers.reduce(
+    (current, layer) => ({
+      minX: Math.min(current.minX, layer.x),
+      minY: Math.min(current.minY, layer.y),
+      maxX: Math.max(current.maxX, layer.x + layer.width),
+      maxY: Math.max(current.maxY, layer.y + layer.height),
+    }),
+    {
+      minX: Number.POSITIVE_INFINITY,
+      minY: Number.POSITIVE_INFINITY,
+      maxX: Number.NEGATIVE_INFINITY,
+      maxY: Number.NEGATIVE_INFINITY,
+    },
+  );
+}
+
+export function resolveSnappedLayerPosition(
+  movingLayer: CanvasLayer,
+  proposedX: number,
+  proposedY: number,
+  layers: CanvasLayer[],
+  scale: number,
+) {
+  return resolveSnappedItemPosition(
+    movingLayer,
+    proposedX,
+    proposedY,
+    layers,
+    scale,
+  );
+}
+
+export function resolveSnappedItemPosition(
+  movingItem: CanvasSnapItem,
+  proposedX: number,
+  proposedY: number,
+  items: CanvasSnapItem[],
+  scale: number,
+) {
+  const threshold = SNAP_THRESHOLD_SCREEN_PX / Math.max(scale, MIN_SCALE);
+  const visibleItems = items.filter(
+    (item) => item.id !== movingItem.id && !item.hidden,
+  );
+  const verticalTargets = [
+    0,
+    CANVAS_WORLD_ORIGIN,
+    ...visibleItems.flatMap((item) => [
+      item.x,
+      item.x + item.width / 2,
+      item.x + item.width,
+    ]),
+  ];
+  const horizontalTargets = [
+    0,
+    CANVAS_WORLD_ORIGIN,
+    ...visibleItems.flatMap((item) => [
+      item.y,
+      item.y + item.height / 2,
+      item.y + item.height,
+    ]),
+  ];
+
+  const xAlignmentSnap = findNearestSnap(
+    proposedX,
+    [0, movingItem.width / 2, movingItem.width],
+    verticalTargets,
+    threshold,
+  );
+  const yAlignmentSnap = findNearestSnap(
+    proposedY,
+    [0, movingItem.height / 2, movingItem.height],
+    horizontalTargets,
+    threshold,
+  );
+  const xDistributionSnap = findNearestEqualSpacingSnap({
+    axis: 'x',
+    proposedStart: proposedX,
+    proposedCrossStart: proposedY,
+    movingSize: movingItem.width,
+    movingCrossSize: movingItem.height,
+    items: visibleItems,
+    threshold,
+  });
+  const yDistributionSnap = findNearestEqualSpacingSnap({
+    axis: 'y',
+    proposedStart: proposedY,
+    proposedCrossStart: proposedX,
+    movingSize: movingItem.height,
+    movingCrossSize: movingItem.width,
+    items: visibleItems,
+    threshold,
+  });
+  const xSnap = chooseNearestSnap(xAlignmentSnap, xDistributionSnap);
+  const ySnap = chooseNearestSnap(yAlignmentSnap, yDistributionSnap);
+
+  return {
+    x: xSnap ? xSnap.position : proposedX,
+    y: ySnap ? ySnap.position : proposedY,
+    guide:
+      xSnap || ySnap
+        ? {
+            vertical: xSnap?.guide,
+            horizontal: ySnap?.guide,
+          }
+        : null,
+  };
+}
+
+function chooseNearestSnap(
+  first: SnapCandidate | null,
+  second: SnapCandidate | null,
+) {
+  if (!first) {
+    return second;
+  }
+  if (!second) {
+    return first;
+  }
+  return second.distance < first.distance ? second : first;
+}
+
+function findNearestEqualSpacingSnap({
+  axis,
+  proposedStart,
+  proposedCrossStart,
+  movingSize,
+  movingCrossSize,
+  items,
+  threshold,
+}: {
+  axis: 'x' | 'y';
+  proposedStart: number;
+  proposedCrossStart: number;
+  movingSize: number;
+  movingCrossSize: number;
+  items: CanvasSnapItem[];
+  threshold: number;
+}): SnapCandidate | null {
+  const orderedItems = [...items].sort(
+    (firstItem, secondItem) =>
+      getSnapItemStart(firstItem, axis) - getSnapItemStart(secondItem, axis),
+  );
+  let nearest: SnapCandidate | null = null;
+
+  for (let firstIndex = 0; firstIndex < orderedItems.length; firstIndex += 1) {
+    const firstItem = orderedItems[firstIndex];
+    if (!firstItem) {
+      continue;
+    }
+    for (
+      let secondIndex = firstIndex + 1;
+      secondIndex < orderedItems.length;
+      secondIndex += 1
+    ) {
+      const secondItem = orderedItems[secondIndex];
+      if (!secondItem) {
+        continue;
+      }
+      if (
+        !snapItemsOverlapOnCrossAxis(
+          proposedCrossStart,
+          movingCrossSize,
+          firstItem,
+          axis,
+        ) ||
+        !snapItemsOverlapOnCrossAxis(
+          proposedCrossStart,
+          movingCrossSize,
+          secondItem,
+          axis,
+        )
+      ) {
+        continue;
+      }
+
+      const firstStart = getSnapItemStart(firstItem, axis);
+      const firstEnd = getSnapItemEnd(firstItem, axis);
+      const secondStart = getSnapItemStart(secondItem, axis);
+      const secondEnd = getSnapItemEnd(secondItem, axis);
+      const pairGap = secondStart - firstEnd;
+      if (pairGap < 0) {
+        continue;
+      }
+
+      nearest = chooseNearestSnap(
+        nearest,
+        createDistributionSnapCandidate({
+          position: firstStart - pairGap - movingSize,
+          proposedStart,
+          movingSize,
+          threshold,
+        }),
+      );
+      nearest = chooseNearestSnap(
+        nearest,
+        createDistributionSnapCandidate({
+          position: secondEnd + pairGap,
+          proposedStart,
+          movingSize,
+          threshold,
+        }),
+      );
+
+      const betweenGap = (pairGap - movingSize) / 2;
+      if (betweenGap >= 0) {
+        nearest = chooseNearestSnap(
+          nearest,
+          createDistributionSnapCandidate({
+            position: firstEnd + betweenGap,
+            proposedStart,
+            movingSize,
+            threshold,
+          }),
+        );
+      }
+    }
+  }
+
+  return nearest;
+}
+
+function createDistributionSnapCandidate({
+  position,
+  proposedStart,
+  movingSize,
+  threshold,
+}: {
+  position: number;
+  proposedStart: number;
+  movingSize: number;
+  threshold: number;
+}): SnapCandidate | null {
+  const distance = Math.abs(position - proposedStart);
+  if (distance > threshold) {
+    return null;
+  }
+  return {
+    position,
+    guide: position + movingSize / 2,
+    distance,
+  };
+}
+
+function getSnapItemStart(item: CanvasSnapItem, axis: 'x' | 'y') {
+  return axis === 'x' ? item.x : item.y;
+}
+
+function getSnapItemSize(item: CanvasSnapItem, axis: 'x' | 'y') {
+  return axis === 'x' ? item.width : item.height;
+}
+
+function getSnapItemEnd(item: CanvasSnapItem, axis: 'x' | 'y') {
+  return getSnapItemStart(item, axis) + getSnapItemSize(item, axis);
+}
+
+function getSnapItemCrossStart(item: CanvasSnapItem, axis: 'x' | 'y') {
+  return axis === 'x' ? item.y : item.x;
+}
+
+function getSnapItemCrossSize(item: CanvasSnapItem, axis: 'x' | 'y') {
+  return axis === 'x' ? item.height : item.width;
+}
+
+function snapItemsOverlapOnCrossAxis(
+  proposedCrossStart: number,
+  movingCrossSize: number,
+  item: CanvasSnapItem,
+  axis: 'x' | 'y',
+) {
+  const movingCrossEnd = proposedCrossStart + movingCrossSize;
+  const itemCrossStart = getSnapItemCrossStart(item, axis);
+  const itemCrossEnd = itemCrossStart + getSnapItemCrossSize(item, axis);
+  return (
+    proposedCrossStart <=
+      itemCrossEnd - SNAP_DISTRIBUTION_OVERLAP_TOLERANCE &&
+    movingCrossEnd >= itemCrossStart + SNAP_DISTRIBUTION_OVERLAP_TOLERANCE
+  );
+}
+
+export function findNearestSnap(
+  origin: number,
+  offsets: number[],
+  targets: number[],
+  threshold: number,
+): SnapCandidate | null {
+  let nearest: SnapCandidate | null = null;
+  for (const offset of offsets) {
+    for (const target of targets) {
+      const distance = Math.abs(target - (origin + offset));
+      if (distance > threshold) {
+        continue;
+      }
+      if (!nearest || distance < nearest.distance) {
+        nearest = {
+          position: target - offset,
+          guide: target,
+          distance,
+        };
+      }
+    }
+  }
+  return nearest;
+}
diff --git a/src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx b/src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx
new file mode 100644
index 000000000..ffe7d1bc4
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorPrimitives.test.tsx
@@ -0,0 +1,78 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { Check } from 'lucide-react';
+import { expect, test, vi } from 'vitest';
+
+import {
+  EditorIconButton,
+  SidebarMediaItem,
+} from './ImageCanvasEditorPrimitives';
+
+test('editor icon button delegates accessible icon chrome to the platform primitive', () => {
+  render(
+    <EditorIconButton
+      label="素材选择模式"
+      title="选择"
+      icon={Check}
+      className="image-canvas-editor__icon-button"
+      pressed
+      expanded
+    />,
+  );
+
+  const button = screen.getByRole('button', { name: '素材选择模式' });
+
+  expect(button.className).toContain('platform-icon-button');
+  expect(button.className).toContain('image-canvas-editor__icon-button');
+  expect(button.getAttribute('title')).toBe('选择');
+  expect(button.getAttribute('aria-pressed')).toBe('true');
+  expect(button.getAttribute('aria-expanded')).toBe('true');
+});
+
+test('editor icon button forwards shared icon button variants', () => {
+  render(
+    <EditorIconButton
+      label="关闭生成图片"
+      title="关闭"
+      icon={Check}
+      variant="surfaceFloating"
+      className="image-canvas-editor__generation-close"
+    />,
+  );
+
+  const button = screen.getByRole('button', { name: '关闭生成图片' });
+
+  expect(button.className).toContain('bg-white/94');
+  expect(button.className).toContain('image-canvas-editor__generation-close');
+});
+
+test('sidebar media item delegates thumbnail chrome to the platform media frame', () => {
+  const onPrimaryClick = vi.fn();
+  render(
+    <SidebarMediaItem
+      title="拼图素材"
+      detail="1024 x 1024"
+      imageSrc="data:image/png;base64,one"
+      imageAlt="素材：拼图素材"
+      primaryLabel="添加拼图素材"
+      onPrimaryClick={onPrimaryClick}
+      rowClassName="image-canvas-editor__asset-row"
+      primaryClassName="image-canvas-editor__asset-button"
+      thumbnailClassName="image-canvas-editor__asset-thumb"
+      metaClassName="image-canvas-editor__asset-meta"
+    />,
+  );
+
+  const button = screen.getByRole('button', { name: '添加拼图素材' });
+  const image = screen.getByRole('img', { name: '素材：拼图素材' });
+  const frame = image.closest('.platform-media-frame');
+
+  expect(frame?.className).toContain('platform-media-frame');
+  expect(frame?.className).toContain('image-canvas-editor__asset-thumb');
+  expect(screen.getByText('1024 x 1024')).toBeTruthy();
+
+  fireEvent.click(button);
+
+  expect(onPrimaryClick).toHaveBeenCalledTimes(1);
+});
diff --git a/src/components/image-editor/ImageCanvasEditorPrimitives.tsx b/src/components/image-editor/ImageCanvasEditorPrimitives.tsx
new file mode 100644
index 000000000..2cf75a5b6
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorPrimitives.tsx
@@ -0,0 +1,148 @@
+import type {
+  ComponentType,
+  DragEventHandler,
+  MouseEventHandler,
+  PointerEventHandler,
+  ReactNode,
+} from 'react';
+
+import {
+  PlatformIconButton,
+  type PlatformIconButtonVariant,
+} from '../common/PlatformIconButton';
+import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
+
+type IconComponent = ComponentType<{ className?: string }>;
+
+export type EditorIconButtonProps = {
+  label: string;
+  title?: string;
+  icon: IconComponent;
+  className?: string;
+  type?: 'button' | 'submit';
+  disabled?: boolean;
+  pressed?: boolean;
+  expanded?: boolean;
+  variant?: PlatformIconButtonVariant;
+  onClick?: () => void;
+};
+
+export function EditorIconButton({
+  label,
+  title = label,
+  icon: Icon,
+  className,
+  type = 'button',
+  disabled,
+  pressed,
+  expanded,
+  variant,
+  onClick,
+}: EditorIconButtonProps) {
+  return (
+    <PlatformIconButton
+      variant={variant}
+      type={type}
+      className={className}
+      label={label}
+      title={title}
+      disabled={disabled}
+      aria-pressed={pressed}
+      aria-expanded={expanded}
+      onClick={onClick}
+      icon={<Icon className="h-4 w-4" />}
+    />
+  );
+}
+
+export type SidebarMediaItemProps = {
+  title: string;
+  detail: string;
+  imageSrc: string;
+  imageAlt: string;
+  selected?: boolean;
+  primaryLabel: string;
+  onPrimaryClick: () => void;
+  thumbnailClassName: string;
+  metaClassName: string;
+  rowClassName: string;
+  primaryClassName?: string;
+  actions?: ReactNode;
+  titleNode?: ReactNode;
+  previewOverlay?: ReactNode;
+  footerNode?: ReactNode;
+  draggable?: boolean;
+  onDragStart?: DragEventHandler<HTMLElement>;
+  onDragEnd?: DragEventHandler<HTMLElement>;
+  onDragOver?: DragEventHandler<HTMLDivElement>;
+  onDrop?: DragEventHandler<HTMLDivElement>;
+  onPointerDown?: PointerEventHandler<HTMLDivElement>;
+  onPointerEnter?: PointerEventHandler<HTMLDivElement>;
+  onContextMenu?: MouseEventHandler<HTMLDivElement>;
+};
+
+export function SidebarMediaItem({
+  title,
+  detail,
+  imageSrc,
+  imageAlt,
+  selected = false,
+  primaryLabel,
+  onPrimaryClick,
+  thumbnailClassName,
+  metaClassName,
+  rowClassName,
+  primaryClassName,
+  actions,
+  titleNode,
+  previewOverlay,
+  footerNode,
+  draggable,
+  onDragStart,
+  onDragEnd,
+  onDragOver,
+  onDrop,
+  onPointerDown,
+  onPointerEnter,
+  onContextMenu,
+}: SidebarMediaItemProps) {
+  return (
+    <div
+      className={`${rowClassName} ${selected ? `${rowClassName}--selected` : ''}`}
+      draggable={draggable}
+      onDragStart={onDragStart}
+      onDragEnd={onDragEnd}
+      onDragOver={onDragOver}
+      onDrop={onDrop}
+      onPointerDown={onPointerDown}
+      onPointerEnter={onPointerEnter}
+      onContextMenu={onContextMenu}
+    >
+      <button
+        type="button"
+        className={primaryClassName}
+        onClick={onPrimaryClick}
+        aria-label={primaryLabel}
+        draggable={draggable}
+        onDragStart={onDragStart}
+        onDragEnd={onDragEnd}
+      >
+        <PlatformMediaFrame
+          src={imageSrc}
+          alt={imageAlt}
+          fallbackLabel={title}
+          aspect="square"
+          surface="none"
+          className={thumbnailClassName}
+          previewOverlay={previewOverlay}
+        />
+      </button>
+      <div className={metaClassName}>
+        {titleNode ?? <span>{title}</span>}
+        <span>{detail}</span>
+        {footerNode}
+      </div>
+      {actions}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasEditorShellView.test.tsx b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
new file mode 100644
index 000000000..18ad713ed
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorShellView.test.tsx
@@ -0,0 +1,267 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ImageCanvasEditorShellView } from './ImageCanvasEditorShellView';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import type { ImageCanvasMetadataModalViewProps } from './ImageCanvasMetadataModalView';
+import type { ImageCanvasSidebarViewProps } from './ImageCanvasSidebarView';
+import type { ImageCanvasStageViewProps } from './ImageCanvasStageView';
+import type { ImageCanvasTopbarViewProps } from './ImageCanvasTopbarView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '测试图片',
+    src: 'data:image/png;base64,layer',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createSidebarProps(): ImageCanvasSidebarViewProps {
+  return {
+    activeSidebarPanel: null,
+    assetListRef: createRef<HTMLDivElement>(),
+    assetPointerDragRef: { current: null },
+    suppressAssetClickRef: { current: false },
+    assets: [],
+    groupedAssets: [],
+    assetFolders: [],
+    layers: [],
+    selectedLayerId: null,
+    selectedLayerIds: [],
+    isAssetSelectionMode: false,
+    selectedAssetIds: new Set(),
+    assetMoveDropFolderId: null,
+    pinnedAssetMoveFolderId: null,
+    creatingFolder: false,
+    newFolderName: '',
+    renamingFolder: null,
+    renamingAsset: null,
+    allSelectableAssetsSelected: false,
+    assetMarquee: null,
+    setIsAssetSelectionMode: vi.fn(),
+    setCreatingFolder: vi.fn(),
+    setNewFolderName: vi.fn(),
+    setRenamingFolder: vi.fn(),
+    setRenamingAsset: vi.fn(),
+    setActiveUploadFolderId: vi.fn(),
+    setUploadDropTarget: vi.fn(),
+    setAssetPointerDrag: vi.fn(),
+    setSelectedAssetIds: vi.fn(),
+    setImageContextMenu: vi.fn(),
+    setContextMenu: vi.fn(),
+    onAssetMarqueePointerDown: vi.fn(),
+    onAssetMarqueePointerMove: vi.fn(),
+    onAssetMarqueePointerUp: vi.fn(),
+    updateAssetMoveDropFolder: vi.fn(),
+    addUploadedFiles: vi.fn(),
+    requestUpload: vi.fn(),
+    moveAssetToFolder: vi.fn(),
+    commitNewAssetFolder: vi.fn(),
+    toggleAssetFolder: vi.fn(),
+    startRenamingFolder: vi.fn(),
+    commitFolderRename: vi.fn(),
+    deleteAssetFolder: vi.fn(),
+    startRenamingAsset: vi.fn(),
+    commitAssetRename: vi.fn(),
+    deleteUploadedAsset: vi.fn(),
+    toggleAssetSelected: vi.fn(),
+    addAssetLayer: vi.fn(),
+    toggleAllAssetsSelected: vi.fn(),
+    deleteSelectedAssets: vi.fn(),
+    closeAssetSelectionMode: vi.fn(),
+    groupSelectedLayers: vi.fn(),
+    selectSingleLayer: vi.fn(),
+    resolveContextMenuPosition: vi.fn(() => ({ x: 0, y: 0 })),
+    getCanvasPointFromClient: vi.fn(() => ({ x: 0, y: 0 })),
+  };
+}
+
+function createTopbarProps(): ImageCanvasTopbarViewProps {
+  return {
+    projectId: 'project-1',
+    projectTitle: '默认项目',
+    projectRenameValue: '默认项目',
+    isRenamingProject: false,
+    isProjectRenameSaving: false,
+    projectRenameError: null,
+    layers: [],
+    assetExportStatus: null,
+    isExportingAssets: false,
+    setProjectRenameValue: vi.fn(),
+    startProjectRename: vi.fn(),
+    cancelProjectRename: vi.fn(),
+    submitProjectRename: vi.fn(),
+    resetProjectRenameError: vi.fn(),
+    exportCanvasAssets: vi.fn(),
+  };
+}
+
+function createStageProps(): ImageCanvasStageViewProps {
+  return {
+    canvasViewportRef: createRef<HTMLDivElement>(),
+    specToolWrapRef: createRef<HTMLSpanElement>(),
+    musicToolWrapRef: createRef<HTMLSpanElement>(),
+    publicationToolWrapRef: createRef<HTMLSpanElement>(),
+    isPanning: false,
+    effectiveTool: 'select',
+    canvasBackgroundColor: '#f8fafc',
+    canvasBackgroundHexValue: '#f8fafc',
+    viewport: { x: 0, y: 0, scale: 1 },
+    snapGuide: null,
+    layers: [],
+    selectedLayer: null,
+    selectedLayerIds: [],
+    hoveredLayerId: null,
+    canvasMarquee: null,
+    canvasGenerationDialogs: [],
+    generateDialog: null,
+    cropExpandPanel: null,
+    cropExpandSourceLayer: null,
+    generationComposerStyle: null,
+    selectedToolbarStyle: null,
+    uploadDropTarget: null,
+    contextMenu: null,
+    canvasClipboard: null,
+    imageContextMenu: null,
+    imageContextMenuLayer: null,
+    contextShouldShowLayer: false,
+    contextShouldUnlockLayer: false,
+    canUndo: false,
+    canRedo: false,
+    isZoomMenuOpen: false,
+    isBackgroundSettingsOpen: false,
+    activeSidebarPanel: null,
+    isMinimapOpen: false,
+    minimapModel: null,
+    onCanvasPointerDown: vi.fn(),
+    onCanvasPointerMove: vi.fn(),
+    onCanvasPointerUp: vi.fn(),
+    onCanvasDragOver: vi.fn(),
+    onCanvasDragLeave: vi.fn(),
+    onCanvasDrop: vi.fn(),
+    onCanvasContextMenu: vi.fn(),
+    onLayerPointerDown: vi.fn(),
+    onLayerClick: vi.fn(),
+    onSelectLayer: vi.fn(),
+    onLayerContextMenu: vi.fn(),
+    onLayerMouseEnter: vi.fn(),
+    onLayerMouseLeave: vi.fn(),
+    onOpenLayerMetadata: vi.fn(),
+    onUpdateLayerAssetKind: vi.fn(),
+    onGenerationFramePointerDown: vi.fn(),
+    onActivateGenerationDialog: vi.fn(),
+    onCropExpandHandlePointerDown: vi.fn(),
+    onOpenQuickEditPanel: vi.fn(),
+    onOpenRedrawPanel: vi.fn(),
+    onOpenCropExpandPanel: vi.fn(),
+    onRemoveBackground: vi.fn(),
+    onExtractUiDesignAssets: vi.fn(),
+    onOpenCharacterAnimationPanel: vi.fn(),
+    onDownloadLayer: vi.fn(),
+    onPasteCanvasClipboard: vi.fn(),
+    onCopyContextLayers: vi.fn(),
+    onDuplicateContextLayers: vi.fn(),
+    onMoveContextLayers: vi.fn(),
+    onGroupContextLayers: vi.fn(),
+    onUngroupContextLayers: vi.fn(),
+    onToggleContextLayerVisibility: vi.fn(),
+    onToggleContextLayerLock: vi.fn(),
+    onFlipContextLayers: vi.fn(),
+    onExportContextLayer: vi.fn(),
+    onDeleteContextLayers: vi.fn(),
+    onDeleteLayerById: vi.fn(),
+    onCloseContextMenu: vi.fn(),
+    onCloseImageContextMenu: vi.fn(),
+    onUpdateScaleFromCenter: vi.fn(),
+    onFitLayers: vi.fn(),
+    onUndoCanvasChange: vi.fn(),
+    onRedoCanvasChange: vi.fn(),
+    onToggleZoomMenu: vi.fn(),
+    onCloseZoomMenu: vi.fn(),
+    onToggleBackgroundSettings: vi.fn(),
+    onApplyCanvasBackgroundColor: vi.fn(),
+    onCanvasBackgroundHexChange: vi.fn(),
+    onToggleSidebarPanel: vi.fn(),
+    onToggleMinimap: vi.fn(),
+    onMinimapPointerDown: vi.fn(),
+    onSwitchTool: vi.fn(),
+    onOpenToolOptions: vi.fn(),
+    onCloseToolOptions: vi.fn(),
+  };
+}
+
+function createMetadataProps(
+  layer: CanvasLayer | null = null,
+): ImageCanvasMetadataModalViewProps {
+  return {
+    layer,
+    onClose: vi.fn(),
+  };
+}
+
+describe('ImageCanvasEditorShellView', () => {
+  it('composes upload input, topbar, stage and metadata modal', () => {
+    const handleUploadInputChange = vi.fn();
+    render(
+      <ImageCanvasEditorShellView
+        editorRootRef={createRef<HTMLElement>()}
+        uploadInputRef={createRef<HTMLInputElement>()}
+        onUploadInputChange={handleUploadInputChange}
+        assetDragPreview={null}
+        sidebarProps={createSidebarProps()}
+        topbarProps={createTopbarProps()}
+        stageProps={createStageProps()}
+        metadataProps={createMetadataProps(createLayer())}
+      />,
+    );
+
+    expect(screen.getByRole('region', { name: '图片画布编辑器' })).toBeTruthy();
+    expect(screen.getByRole('heading', { name: '默认项目' })).toBeTruthy();
+    expect(screen.getByLabelText('画布工作区')).toBeTruthy();
+    expect(screen.getByRole('toolbar', { name: 'AI画布工具栏' })).toBeTruthy();
+    expect(screen.getByRole('dialog', { name: '图片信息' })).toBeTruthy();
+
+    const uploadInput = screen.getByLabelText(
+      '上传图片文件',
+    ) as HTMLInputElement;
+    fireEvent.change(uploadInput);
+
+    expect(uploadInput.multiple).toBe(true);
+    expect(uploadInput.accept).toBe('image/*');
+    expect(handleUploadInputChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the asset drag preview with sanitized coordinates', () => {
+    render(
+      <ImageCanvasEditorShellView
+        editorRootRef={createRef<HTMLElement>()}
+        uploadInputRef={createRef<HTMLInputElement>()}
+        onUploadInputChange={vi.fn()}
+        assetDragPreview={{ x: Number.NaN, y: 48, label: '拖拽素材' }}
+        sidebarProps={createSidebarProps()}
+        topbarProps={createTopbarProps()}
+        stageProps={createStageProps()}
+        metadataProps={createMetadataProps()}
+      />,
+    );
+
+    const preview = screen.getByText('拖拽素材');
+
+    expect(preview.className).toBe('image-canvas-editor__asset-drag-preview');
+    expect((preview as HTMLElement).style.left).toBe('0px');
+    expect((preview as HTMLElement).style.top).toBe('48px');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasEditorShellView.tsx b/src/components/image-editor/ImageCanvasEditorShellView.tsx
new file mode 100644
index 000000000..1701d3f47
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorShellView.tsx
@@ -0,0 +1,84 @@
+import type {
+  ChangeEventHandler,
+  ComponentProps,
+  RefObject,
+} from 'react';
+
+import { ImageCanvasMetadataModalView } from './ImageCanvasMetadataModalView';
+import { ImageCanvasSidebarView } from './ImageCanvasSidebarView';
+import { ImageCanvasStageView } from './ImageCanvasStageView';
+import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
+
+type AssetDragPreview = {
+  x: number;
+  y: number;
+  label: string;
+};
+
+type ImageCanvasEditorShellViewProps = {
+  editorRootRef: RefObject<HTMLElement | null>;
+  uploadInputRef: RefObject<HTMLInputElement | null>;
+  uploadAccept?: string;
+  onUploadInputChange: ChangeEventHandler<HTMLInputElement>;
+  assetDragPreview: AssetDragPreview | null;
+  sidebarProps: ComponentProps<typeof ImageCanvasSidebarView>;
+  topbarProps: ComponentProps<typeof ImageCanvasTopbarView>;
+  stageProps: ComponentProps<typeof ImageCanvasStageView>;
+  metadataProps: ComponentProps<typeof ImageCanvasMetadataModalView>;
+};
+
+export function ImageCanvasEditorShellView({
+  editorRootRef,
+  uploadInputRef,
+  uploadAccept = 'image/*',
+  onUploadInputChange,
+  assetDragPreview,
+  sidebarProps,
+  topbarProps,
+  stageProps,
+  metadataProps,
+}: ImageCanvasEditorShellViewProps) {
+  const uploadInputLabel =
+    uploadAccept.includes('video') || uploadAccept.includes('audio')
+      ? '上传媒体文件'
+      : '上传图片文件';
+
+  return (
+    <section
+      ref={editorRootRef}
+      className="image-canvas-editor"
+      aria-label="图片画布编辑器"
+      onContextMenu={(event) => event.preventDefault()}
+    >
+      <input
+        ref={uploadInputRef}
+        type="file"
+        accept={uploadAccept}
+        multiple
+        aria-label={uploadInputLabel}
+        hidden
+        onChange={onUploadInputChange}
+      />
+      {assetDragPreview ? (
+        <div
+          className="image-canvas-editor__asset-drag-preview"
+          style={{
+            left: Number.isFinite(assetDragPreview.x) ? assetDragPreview.x : 0,
+            top: Number.isFinite(assetDragPreview.y) ? assetDragPreview.y : 0,
+          }}
+          aria-hidden="true"
+        >
+          {assetDragPreview.label}
+        </div>
+      ) : null}
+      <ImageCanvasSidebarView {...sidebarProps} />
+
+      <div className="image-canvas-editor__main">
+        <ImageCanvasTopbarView {...topbarProps} />
+        <ImageCanvasStageView {...stageProps} />
+      </div>
+
+      <ImageCanvasMetadataModalView {...metadataProps} />
+    </section>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasEditorTypes.ts b/src/components/image-editor/ImageCanvasEditorTypes.ts
new file mode 100644
index 000000000..0b7183f11
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorTypes.ts
@@ -0,0 +1,493 @@
+import type {
+  EditorAssetSnapshot,
+  EditorCharacterAnimationFrameCount,
+  EditorCharacterAnimationGenerationResult,
+  EditorCharacterAnimationRatio,
+  EditorCharacterAnimationResolution,
+  EditorVideoAspectRatio,
+  EditorVideoModel,
+  EditorVideoResolution,
+  EditorVideoSoundMode,
+} from '../../services/image-editor/editorProjectClient';
+
+export type CanvasSourceType = 'uploaded' | 'generated' | 'mock_generated';
+
+export type CanvasAssetKind =
+  | 'spec'
+  | 'character'
+  | 'character-animation'
+  | 'icon'
+  | 'icon-spritesheet'
+  | 'icon-spec'
+  | 'publication-material'
+  | 'ui-design'
+  | 'video'
+  | 'sound-effect'
+  | 'background-music';
+
+export type CanvasMediaType = 'image' | 'video' | 'audio';
+
+export type EditorAsset = {
+  id: string;
+  label: string;
+  src: string;
+  mediaType?: CanvasMediaType;
+  thumbnailSrc?: string | null;
+  width: number;
+  height: number;
+  folderId: string;
+  sourceKind: 'built-in' | 'uploaded';
+  sourceType: CanvasSourceType;
+  persisted: boolean;
+  prompt?: string;
+  actualPrompt?: string;
+  model?: string;
+  provider?: string;
+  taskId?: string;
+  objectKey?: string;
+  assetObjectId?: string;
+  assetKind?: CanvasAssetKind | null;
+  generationInputs?: CanvasGenerationInputs | null;
+  durationSeconds?: number;
+  uploadStatus?: 'uploading' | 'failed';
+  uploadProgress?: number;
+  uploadMessage?: string;
+};
+
+export type CanvasGenerationInputField = {
+  title: string;
+  value: string;
+};
+
+export type CanvasGenerationInputReference = {
+  title: string;
+  label: string;
+  refType: 'project-resource' | 'asset';
+  refId: string;
+};
+
+export type CanvasGenerationInputs = {
+  fields: CanvasGenerationInputField[];
+  references: CanvasGenerationInputReference[];
+};
+
+export type CanvasLayer = {
+  id: string;
+  resourceId: string;
+  title: string;
+  src: string;
+  mediaType?: CanvasMediaType;
+  thumbnailSrc?: string | null;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  originalWidth: number;
+  originalHeight: number;
+  zIndex: number;
+  sourceType: CanvasSourceType;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  sourceResourceId?: string | null;
+  sourceAssetId?: string | null;
+  generatedAssetSnapshot?: EditorAssetSnapshot | null;
+  groupId?: string | null;
+  assetKind?: CanvasAssetKind | null;
+  generationInputs?: CanvasGenerationInputs | null;
+  durationSeconds?: number;
+  hidden?: boolean;
+  locked?: boolean;
+  flipX?: boolean;
+  flipY?: boolean;
+};
+
+export type CanvasViewport = {
+  x: number;
+  y: number;
+  scale: number;
+};
+
+export type CanvasTool =
+  | 'select'
+  | 'hand'
+  | 'upload'
+  | 'generate'
+  | 'video'
+  | 'music'
+  | 'spec'
+  | 'character'
+  | 'icon'
+  | 'publication'
+  | 'ui-design';
+
+export type SidebarPanel = 'assets' | 'layers';
+
+export type EditorAssetFolder = {
+  id: string;
+  label: string;
+  collapsed: boolean;
+  systemDefault: boolean;
+  persisted: boolean;
+};
+
+export type SpecGenerationType = 'character' | 'ui' | 'icon' | 'custom';
+
+export type SpecFormValues = {
+  playSetting: string;
+  artStyle: string;
+  bodyRatio: string;
+  characterView: string;
+  customPrompt: string;
+};
+
+export type CharacterReferenceImage = {
+  id: string;
+  label: string;
+  src: string;
+  mediaType?: CanvasMediaType;
+  mimeType?: string;
+  sizeBytes?: number;
+  durationSeconds?: number;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  resourceId?: string | null;
+  sourceAssetId?: string | null;
+};
+
+export type PublicationMaterialsGameInfo = {
+  gameName: string;
+  gameCategories: string;
+  gameDescription: string;
+};
+
+export type PublicationMaterialsWorkflowId =
+  | 'publication-cover-image'
+  | 'publication-detail-gallery'
+  | 'publication-promo-poster';
+
+export type GenerateDialogState = {
+  id?: string;
+  mode:
+    | 'generate'
+    | 'edit'
+    | 'spec'
+    | 'character'
+    | 'icon'
+    | 'publication'
+    | 'ui-design'
+    | 'quick-edit'
+    | 'character-animation'
+    | 'video'
+    | 'audio-sound-effect'
+    | 'audio-background-music';
+  prompt: string;
+  status: 'idle' | 'generating' | 'failed';
+  composerOpen?: boolean;
+  sourceLayerId?: string;
+  generatedLayerId?: string;
+  specType?: SpecGenerationType;
+  specValues?: SpecFormValues;
+  specReference?: CharacterReferenceImage | null;
+  generationReferences?: CharacterReferenceImage[];
+  characterSpecReference?: CharacterReferenceImage | null;
+  characterReferences?: CharacterReferenceImage[];
+  iconSpecReference?: CharacterReferenceImage | null;
+  iconDescriptions?: string[];
+  publicationWorkflowId?: PublicationMaterialsWorkflowId;
+  publicationGameInfo?: PublicationMaterialsGameInfo;
+  publicationReferences?: CharacterReferenceImage[];
+  uiDesignSpecReference?: CharacterReferenceImage | null;
+  imageModel?: string;
+  videoModel?: EditorVideoModel;
+  videoAspectRatio?: EditorVideoAspectRatio;
+  videoResolution?: EditorVideoResolution;
+  videoDurationSeconds?: number;
+  videoMode?: 'std';
+  videoSound?: EditorVideoSoundMode;
+  videoWebSearchEnabled?: boolean;
+  characterAnimationResolution?: EditorCharacterAnimationResolution;
+  characterAnimationRatio?: EditorCharacterAnimationRatio;
+  characterAnimationFrameCount?: EditorCharacterAnimationFrameCount;
+  characterAnimationDurationSeconds?: 4 | 5 | 6;
+  characterAnimationResult?: EditorCharacterAnimationGenerationResult;
+  soundModel?: 'audio1.0';
+  // 中文注释：Vidu 文生音频 duration 只允许 2-10 秒，默认 5 秒。
+  soundDurationSeconds?: number;
+  makeInstrumental?: boolean;
+  audioDurationSeconds?: number | null;
+  aspectRatio?: string;
+  imageSize?: string;
+  errorMessage?: string;
+  placeholder?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+  };
+};
+
+export type CanvasGenerationDialogMode = Exclude<
+  GenerateDialogState['mode'],
+  'edit'
+>;
+
+export type CanvasGenerationDialogState = GenerateDialogState & {
+  id: string;
+  mode: CanvasGenerationDialogMode;
+};
+
+export type ImageContextMenuState = {
+  layerId: string;
+  x: number;
+  y: number;
+};
+
+export type CanvasHistorySnapshot = {
+  layers: CanvasLayer[];
+  viewport: CanvasViewport;
+  generateDialog: GenerateDialogState | null;
+  inactiveGenerateDialogs: CanvasGenerationDialogState[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+};
+
+export type CanvasClipboard = {
+  layers: CanvasLayer[];
+  mode: 'copy' | 'cut';
+};
+
+export type CanvasContextMenuState =
+  | {
+      kind: 'blank';
+      x: number;
+      y: number;
+      canvasPoint: { x: number; y: number };
+    }
+  | {
+      kind: 'layer';
+      x: number;
+      y: number;
+      layerId: string;
+      canvasPoint: { x: number; y: number };
+    };
+
+export type QuickEditPanelState = {
+  mode?: 'quick-edit' | 'redraw';
+  sourceLayerId: string;
+  prompt: string;
+  size: string;
+  aspectRatio?: string;
+  imageSize?: string;
+  model: string;
+  quickEditReferences?: CharacterReferenceImage[];
+  status: 'idle' | 'generating' | 'failed';
+  errorMessage?: string;
+};
+
+export type CropExpandPanelState = {
+  sourceLayerId: string;
+  frame: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  ratio: CropExpandRatioValue;
+  status: 'idle' | 'processing' | 'failed';
+  errorMessage?: string;
+};
+
+export type CropExpandRatioValue =
+  | 'free'
+  | '1:1'
+  | '4:3'
+  | '3:4'
+  | '16:9'
+  | '9:16';
+
+export type CropExpandResizeHandle =
+  | 'left'
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+export type CharacterAnimationPanelState = {
+  sourceLayerId: string;
+  promptText: string;
+  resolution: EditorCharacterAnimationResolution;
+  ratio: EditorCharacterAnimationRatio;
+  frameCount: EditorCharacterAnimationFrameCount;
+  durationSeconds: 4 | 5 | 6;
+  status: 'idle' | 'generating' | 'completed' | 'failed';
+  errorMessage?: string;
+  result?: EditorCharacterAnimationGenerationResult;
+};
+
+export type UploadTarget =
+  | 'asset'
+  | 'generation-reference'
+  | 'quick-edit-reference'
+  | 'video-reference-image'
+  | 'video-reference-video'
+  | 'video-reference-audio'
+  | 'spec-reference'
+  | 'character-spec'
+  | 'character-reference'
+  | 'icon-spec'
+  | 'ui-design-icon-spec'
+  | 'publication-reference';
+
+export type SnapGuide = {
+  vertical?: number;
+  horizontal?: number;
+};
+
+export type SnapCandidate = {
+  position: number;
+  guide: number;
+  distance: number;
+};
+
+export type CanvasSnapItem = {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  hidden?: boolean;
+};
+
+export type AssetMarqueeState = {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  currentX: number;
+  currentY: number;
+};
+
+export type AssetPointerDragState = {
+  pointerId: number;
+  assetId: string;
+  startClientX: number;
+  startClientY: number;
+  currentClientX: number;
+  currentClientY: number;
+  active: boolean;
+  dropFolderId: string | null;
+};
+
+export type CanvasMarqueeState = {
+  pointerId: number;
+  startX: number;
+  startY: number;
+  currentX: number;
+  currentY: number;
+};
+
+export type DragState =
+  | {
+      kind: 'pan';
+      pointerId: number;
+      startClientX: number;
+      startClientY: number;
+      startViewport: CanvasViewport;
+    }
+  | {
+      kind: 'layer';
+      pointerId: number;
+      layerId: string;
+      layerIds: string[];
+      generationDialogIds?: string[];
+      startClientX: number;
+      startClientY: number;
+      startLayerX: number;
+      startLayerY: number;
+      startLayers: Array<{ id: string; x: number; y: number }>;
+      startGenerationFrames?: Array<{ id: string; x: number; y: number }>;
+      startScale: number;
+    }
+  | {
+      kind: 'generation-frame';
+      dialogId: string;
+      dialogIds: string[];
+      layerIds: string[];
+      pointerId: number;
+      startClientX: number;
+      startClientY: number;
+      startFrameX: number;
+      startFrameY: number;
+      startFrames: Array<{ id: string; x: number; y: number }>;
+      startLayers: Array<{ id: string; x: number; y: number }>;
+      startScale: number;
+    }
+  | {
+      kind: 'minimap';
+      pointerId: number;
+      startClientX: number;
+      startClientY: number;
+      startViewport: CanvasViewport;
+      minimapScale: number;
+      moved: boolean;
+    };
+
+export type CanvasAssetExportImage = {
+  key: string;
+  file: string;
+  layer: CanvasLayer;
+  blob?: Blob;
+  error?: string;
+};
+
+export type CanvasAssetExportMetadata = {
+  projectId: string | null;
+  projectTitle: string;
+  exportedAt: string;
+  layers: Array<{
+    layerId: string;
+    title: string;
+    file: string | null;
+    mediaType?: CanvasMediaType | null;
+    sourceType: CanvasSourceType;
+    prompt?: string | null;
+    actualPrompt?: string | null;
+    model?: string | null;
+    provider?: string | null;
+    taskId?: string | null;
+    objectKey?: string | null;
+    assetObjectId?: string | null;
+    sourceResourceId?: string | null;
+    sourceAssetId?: string | null;
+    exportError?: string;
+    canvas: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+      originalWidth: number;
+      originalHeight: number;
+      zIndex: number;
+      groupId?: string | null;
+      hidden?: boolean;
+      locked?: boolean;
+      flipX?: boolean;
+      flipY?: boolean;
+    };
+  }>;
+  failedImages: Array<{
+    key: string;
+    title: string;
+    src: string;
+    error: string;
+  }>;
+};
diff --git a/src/components/image-editor/ImageCanvasEditorView.test-utils.ts b/src/components/image-editor/ImageCanvasEditorView.test-utils.ts
new file mode 100644
index 000000000..6338a1ceb
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorView.test-utils.ts
@@ -0,0 +1,350 @@
+import JSZip from 'jszip';
+import type { ContextType } from 'react';
+import { fireEvent } from '@testing-library/react';
+import { afterEach, beforeEach, expect, type Mock, vi } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import { AuthUiContext } from '../auth/AuthUiContext';
+import { ImageCanvasEditorView } from './ImageCanvasEditorView';
+
+export { ApiClientError, AuthUiContext, ImageCanvasEditorView };
+
+export type AuthValue = NonNullable<
+  ContextType<typeof AuthUiContext>
+>;
+
+export type ImageCanvasEditorViewServiceMocks = {
+  generateEditorImageMock: Mock;
+  generateEditorIconSpritesheetMock: Mock;
+  extractEditorUiDesignAssetsMock?: Mock;
+  generateEditorCharacterAnimationMock: Mock;
+  editEditorImageMock: Mock;
+  createEditorAssetMock: Mock;
+  createEditorProjectResourceMock: Mock;
+  createEditorAssetFolderMock: Mock;
+  updateEditorAssetMock: Mock;
+  updateEditorAssetFolderMock: Mock;
+  deleteEditorAssetFolderMock: Mock;
+  deleteEditorAssetMock: Mock;
+  loadEditorAssetLibraryMock: Mock;
+  loadEditorProjectMock: Mock;
+  loadOrCreateRecentEditorProjectMock: Mock;
+  renameEditorProjectMock: Mock;
+  saveEditorProjectLayoutMock: Mock;
+};
+
+const runRequiredAuthAction = (action: () => void) => action();
+
+export function createAuthValue(overrides: Partial<AuthValue> = {}): AuthValue {
+  return {
+    user: null,
+    canAccessProtectedData: false,
+    openLoginModal: vi.fn(),
+    requireAuth: vi.fn(runRequiredAuthAction),
+    openSettingsModal: vi.fn(),
+    openAccountModal: vi.fn(),
+    setCurrentUser: vi.fn(),
+    logout: vi.fn(),
+    musicVolume: 0.5,
+    setMusicVolume: vi.fn(),
+    platformTheme: 'light',
+    setPlatformTheme: vi.fn(),
+    isHydratingSettings: false,
+    isPersistingSettings: false,
+    settingsError: null,
+    ...overrides,
+  };
+}
+
+export const defaultEditorProjectResources = [
+  {
+    resourceId: 'resource-puzzle',
+    projectId: 'editor-project-default',
+    imageSrc: '/creation-type-references/puzzle.webp',
+    width: 640,
+    height: 640,
+    sourceType: 'uploaded',
+  },
+  {
+    resourceId: 'resource-big-fish',
+    projectId: 'editor-project-default',
+    imageSrc: '/creation-type-references/big-fish.webp',
+    width: 720,
+    height: 405,
+    sourceType: 'uploaded',
+  },
+];
+
+export const defaultEditorProjectLayers = [
+  {
+    layerId: 'layer-puzzle',
+    resourceId: 'resource-puzzle',
+    title: '拼图素材',
+    x: 470,
+    y: 300,
+    width: 640,
+    height: 640,
+    originalWidth: 640,
+    originalHeight: 640,
+    zIndex: 1,
+    sourceType: 'uploaded',
+  },
+  {
+    layerId: 'layer-big-fish',
+    resourceId: 'resource-big-fish',
+    title: '大鱼素材',
+    x: 930,
+    y: 360,
+    width: 720,
+    height: 405,
+    originalWidth: 720,
+    originalHeight: 405,
+    zIndex: 2,
+    sourceType: 'uploaded',
+  },
+];
+
+export const defaultEditorAssetLibraryAssets = [
+  {
+    assetId: 'asset-puzzle',
+    folderId: 'project',
+    label: '拼图素材',
+    imageSrc: '/creation-type-references/puzzle.webp',
+    width: 640,
+    height: 640,
+    sourceType: 'uploaded',
+  },
+  {
+    assetId: 'asset-match3d',
+    folderId: 'project',
+    label: '抓大鹅素材',
+    imageSrc: '/creation-type-references/match3d.webp',
+    width: 640,
+    height: 640,
+    sourceType: 'uploaded',
+  },
+  {
+    assetId: 'asset-big-fish',
+    folderId: 'project',
+    label: '大鱼素材',
+    imageSrc: '/creation-type-references/big-fish.webp',
+    width: 720,
+    height: 405,
+    sourceType: 'uploaded',
+  },
+  {
+    assetId: 'asset-bark-battle',
+    folderId: 'project',
+    label: '声浪素材',
+    imageSrc: '/creation-type-references/bark-battle.webp',
+    width: 640,
+    height: 900,
+    sourceType: 'uploaded',
+  },
+  {
+    assetId: 'asset-visual-novel',
+    folderId: 'project',
+    label: '视觉小说素材',
+    imageSrc: '/creation-type-references/visual-novel.webp',
+    width: 720,
+    height: 405,
+    sourceType: 'uploaded',
+  },
+];
+
+export function dispatchPointerEvent(
+  target: Element,
+  type: string,
+  init: MouseEventInit & { pointerId: number },
+) {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  Object.defineProperty(event, 'pointerId', { value: init.pointerId });
+  fireEvent(target, event);
+}
+
+export function immediateAsync<T>(value: T) {
+  return {
+    then(onFulfilled: (value: T) => unknown) {
+      onFulfilled(value);
+      return {
+        catch() {},
+      };
+    },
+  };
+}
+
+export function createDataTransferStub() {
+  const store = new Map<string, string>();
+  return {
+    files: [],
+    types: [] as string[],
+    dropEffect: 'none',
+    effectAllowed: 'all',
+    setData(type: string, value: string) {
+      store.set(type, value);
+      if (!this.types.includes(type)) {
+        this.types.push(type);
+      }
+    },
+    getData(type: string) {
+      return store.get(type) ?? '';
+    },
+  };
+}
+
+export function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+
+export async function readZipText(zip: JSZip, path: string) {
+  const file = zip.file(path);
+  expect(file).toBeTruthy();
+  return file!.async('string');
+}
+
+export function setupImageCanvasEditorViewTestLifecycle({
+  generateEditorImageMock,
+  generateEditorIconSpritesheetMock,
+  extractEditorUiDesignAssetsMock,
+  generateEditorCharacterAnimationMock,
+  editEditorImageMock,
+  createEditorAssetMock,
+  createEditorProjectResourceMock,
+  createEditorAssetFolderMock,
+  updateEditorAssetMock,
+  updateEditorAssetFolderMock,
+  deleteEditorAssetFolderMock,
+  deleteEditorAssetMock,
+  loadEditorAssetLibraryMock,
+  loadEditorProjectMock,
+  loadOrCreateRecentEditorProjectMock,
+  renameEditorProjectMock,
+  saveEditorProjectLayoutMock,
+}: ImageCanvasEditorViewServiceMocks) {
+  beforeEach(() => {
+    loadOrCreateRecentEditorProjectMock.mockImplementation(() =>
+      immediateAsync({
+        projectId: 'editor-project-default',
+        title: '默认项目',
+        viewport: { x: 0, y: 0, scale: 1 },
+        layers: defaultEditorProjectLayers,
+        resources: defaultEditorProjectResources,
+        updatedAt: '2026-06-12T00:00:00.000Z',
+      }),
+    );
+    loadEditorAssetLibraryMock.mockImplementation(() =>
+      immediateAsync({
+        folders: [
+          {
+            folderId: 'project',
+            label: '项目素材',
+            sortOrder: 0,
+            collapsed: false,
+            systemDefault: true,
+          },
+        ],
+        assets: defaultEditorAssetLibraryAssets,
+      }),
+    );
+    createEditorAssetMock.mockImplementation(async (input) => ({
+      assetId: `persisted-${input.label}`,
+      folderId: input.folderId,
+      label: input.label,
+      imageSrc: input.imageSrc,
+      objectKey: input.objectKey,
+      assetObjectId: input.assetObjectId,
+      width: input.width,
+      height: input.height,
+      sourceType: input.sourceType,
+      assetKind: input.assetKind,
+      generationInputs: input.generationInputs,
+      durationSeconds: input.durationSeconds,
+    }));
+    createEditorAssetFolderMock.mockResolvedValue({
+      folderId: 'folder-role-persisted',
+      label: '角色上传',
+      collapsed: false,
+      systemDefault: false,
+    });
+    updateEditorAssetMock.mockImplementation(async (assetId, input) => ({
+      assetId,
+      folderId: input.folderId ?? 'project',
+      label: input.label ?? '拼图素材',
+      imageSrc: '/creation-type-references/puzzle.webp',
+      width: 640,
+      height: 640,
+      sourceType: 'uploaded',
+    }));
+    renameEditorProjectMock.mockImplementation(async (projectId, title) => ({
+      projectId,
+      title,
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: defaultEditorProjectLayers,
+      resources: defaultEditorProjectResources,
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    }));
+    updateEditorAssetFolderMock.mockImplementation(async (folderId, input) => ({
+      folderId,
+      label: input.label ?? '角色上传',
+      collapsed: input.collapsed ?? false,
+      systemDefault: false,
+    }));
+    deleteEditorAssetFolderMock.mockResolvedValue({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+    deleteEditorAssetMock.mockResolvedValue({});
+    createEditorProjectResourceMock.mockImplementation(
+      async (projectId, input) => ({
+        resourceId: `resource-${projectId}-${input.width}`,
+        projectId,
+        imageSrc: input.imageSrc,
+        width: input.width,
+        height: input.height,
+        sourceType: input.sourceType,
+      }),
+    );
+    saveEditorProjectLayoutMock.mockResolvedValue({});
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    generateEditorImageMock.mockReset();
+    generateEditorIconSpritesheetMock.mockReset();
+    extractEditorUiDesignAssetsMock?.mockReset();
+    generateEditorCharacterAnimationMock.mockReset();
+    editEditorImageMock.mockReset();
+    createEditorAssetMock.mockReset();
+    createEditorProjectResourceMock.mockReset();
+    createEditorAssetFolderMock.mockReset();
+    updateEditorAssetMock.mockReset();
+    updateEditorAssetFolderMock.mockReset();
+    deleteEditorAssetFolderMock.mockReset();
+    deleteEditorAssetMock.mockReset();
+    loadEditorAssetLibraryMock.mockReset();
+    loadEditorProjectMock.mockReset();
+    loadOrCreateRecentEditorProjectMock.mockReset();
+    renameEditorProjectMock.mockReset();
+    saveEditorProjectLayoutMock.mockReset();
+    window.history.replaceState(null, '', '/editor/canvas');
+  });
+}
diff --git a/src/components/image-editor/ImageCanvasEditorView.test.tsx b/src/components/image-editor/ImageCanvasEditorView.test.tsx
new file mode 100644
index 000000000..460d90e81
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorView.test.tsx
@@ -0,0 +1,1591 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import JSZip from 'jszip';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ApiClientError,
+  AuthUiContext,
+  createAuthValue,
+  dispatchPointerEvent,
+  ImageCanvasEditorView,
+  readZipText,
+  setupImageCanvasEditorViewTestLifecycle,
+} from './ImageCanvasEditorView.test-utils';
+
+const generateEditorImageMock = vi.hoisted(() => vi.fn());
+const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
+const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
+const editEditorImageMock = vi.hoisted(() => vi.fn());
+const createEditorAssetMock = vi.hoisted(() => vi.fn());
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const createEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetMock = vi.hoisted(() => vi.fn());
+const loadEditorAssetLibraryMock = vi.hoisted(() => vi.fn());
+const loadEditorProjectMock = vi.hoisted(() => vi.fn());
+const loadOrCreateRecentEditorProjectMock = vi.hoisted(() => vi.fn());
+const renameEditorProjectMock = vi.hoisted(() => vi.fn());
+const saveEditorProjectLayoutMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: editEditorImageMock,
+    createEditorAsset: createEditorAssetMock,
+    createEditorAssetFolder: createEditorAssetFolderMock,
+    createEditorProjectResource: createEditorProjectResourceMock,
+    deleteEditorAsset: deleteEditorAssetMock,
+    deleteEditorAssetFolder: deleteEditorAssetFolderMock,
+    generateEditorCharacterAnimation: generateEditorCharacterAnimationMock,
+    generateEditorIconSpritesheet: generateEditorIconSpritesheetMock,
+    generateEditorImage: generateEditorImageMock,
+    loadEditorAssetLibrary: loadEditorAssetLibraryMock,
+    loadEditorProject: loadEditorProjectMock,
+    loadOrCreateRecentEditorProject: loadOrCreateRecentEditorProjectMock,
+    renameEditorProject: renameEditorProjectMock,
+    saveEditorProjectLayout: saveEditorProjectLayoutMock,
+    updateEditorAsset: updateEditorAssetMock,
+    updateEditorAssetFolder: updateEditorAssetFolderMock,
+  };
+});
+
+describe('ImageCanvasEditorView', () => {
+  setupImageCanvasEditorViewTestLifecycle({
+    generateEditorImageMock,
+    generateEditorIconSpritesheetMock,
+    generateEditorCharacterAnimationMock,
+    editEditorImageMock,
+    createEditorAssetMock,
+    createEditorProjectResourceMock,
+    createEditorAssetFolderMock,
+    updateEditorAssetMock,
+    updateEditorAssetFolderMock,
+    deleteEditorAssetFolderMock,
+    deleteEditorAssetMock,
+    loadEditorAssetLibraryMock,
+    loadEditorProjectMock,
+    loadOrCreateRecentEditorProjectMock,
+    renameEditorProjectMock,
+    saveEditorProjectLayoutMock,
+  });
+
+  it('loads the project from projectid query before falling back to recent project', async () => {
+    loadEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-query',
+      title: '查询项目',
+      viewport: { x: 12, y: 16, scale: 0.8 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    window.history.replaceState(
+      null,
+      '',
+      '/editor/canvas?projectid=editor-project-query',
+    );
+
+    render(<ImageCanvasEditorView />);
+
+    await waitFor(() => {
+      expect(loadEditorProjectMock).toHaveBeenCalledWith(
+        'editor-project-query',
+      );
+    });
+    expect(loadOrCreateRecentEditorProjectMock).not.toHaveBeenCalled();
+  });
+
+  it('shows the loaded project title and a topbar entry back to projects', async () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(
+      await screen.findByRole('heading', { name: '默认项目' }),
+    ).toBeTruthy();
+    const projectLink = screen.getByRole('link', { name: '返回项目页面' });
+
+    expect(projectLink.getAttribute('href')).toBe('/project');
+    expect(screen.queryByRole('heading', { name: '图片编辑器' })).toBeNull();
+  });
+
+  it('opens login modal when the asset library is unauthorized', async () => {
+    const openLoginModal = vi.fn();
+    loadEditorAssetLibraryMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+
+    render(
+      <AuthUiContext.Provider
+        value={createAuthValue({
+          user: {
+            id: 'user-1',
+            publicUserCode: 'U001',
+            displayName: '测试用户',
+            avatarUrl: null,
+            phoneNumberMasked: '138****0000',
+            loginMethod: 'password',
+            bindingStatus: 'active',
+            wechatBound: false,
+          },
+          canAccessProtectedData: true,
+          openLoginModal,
+        })}
+      >
+        <ImageCanvasEditorView />
+      </AuthUiContext.Provider>,
+    );
+
+    await waitFor(() => {
+      expect(openLoginModal).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('opens the login modal immediately when entering the editor while logged out', async () => {
+    const openLoginModal = vi.fn();
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue({ openLoginModal })}>
+        <ImageCanvasEditorView />
+      </AuthUiContext.Provider>,
+    );
+
+    await waitFor(() => {
+      expect(openLoginModal).toHaveBeenCalledTimes(1);
+    });
+    expect(typeof openLoginModal.mock.calls[0]?.[0]).toBe('function');
+    expect(loadEditorAssetLibraryMock).not.toHaveBeenCalled();
+    expect(loadEditorProjectMock).not.toHaveBeenCalled();
+    expect(loadOrCreateRecentEditorProjectMock).not.toHaveBeenCalled();
+  });
+
+  it('renames the current project from the canvas topbar', async () => {
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByRole('heading', { name: '默认项目' });
+    fireEvent.click(screen.getByRole('button', { name: '编辑项目名称' }));
+    fireEvent.change(screen.getByLabelText('项目名称'), {
+      target: { value: '新画布项目' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '保存项目名称' }));
+
+    await waitFor(() => {
+      expect(renameEditorProjectMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        '新画布项目',
+      );
+    });
+    expect(
+      await screen.findByRole('heading', { name: '新画布项目' }),
+    ).toBeTruthy();
+  });
+
+  it('does not inject built-in mock assets when the persisted library is empty', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-empty',
+      title: '空画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    expect(
+      await screen.findByRole('region', { name: '项目素材' }),
+    ).toBeTruthy();
+    expect(screen.queryByRole('button', { name: '添加拼图素材' })).toBeNull();
+    expect(screen.queryByRole('button', { name: '添加大鱼素材' })).toBeNull();
+    expect(screen.queryByAltText(/画布图片：拼图素材/u)).toBeNull();
+  });
+
+  it('exports valid canvas assets as a zip from the topbar with metadata', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-export',
+      title: '导出项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-data-a',
+          resourceId: 'resource-data-a',
+          title: '素材/A',
+          src: 'data:image/png;base64,YQ==',
+          x: 12,
+          y: 24,
+          width: 320,
+          height: 220,
+          originalWidth: 640,
+          originalHeight: 440,
+          zIndex: 1,
+          sourceType: 'uploaded',
+          sourceAssetId: 'asset-data-a',
+          groupId: 'group-a',
+          hidden: true,
+          locked: true,
+          flipX: true,
+        },
+        {
+          layerId: 'layer-data-a-copy',
+          resourceId: 'resource-data-a-copy',
+          title: '素材/A 副本',
+          src: 'data:image/png;base64,YQ==',
+          x: 42,
+          y: 54,
+          width: 320,
+          height: 220,
+          originalWidth: 640,
+          originalHeight: 440,
+          zIndex: 2,
+          sourceType: 'uploaded',
+          sourceAssetId: 'asset-data-a',
+        },
+        {
+          layerId: 'layer-generated',
+          resourceId: 'resource-generated',
+          title: '生成图',
+          src: '/generated-ok.png',
+          x: 70,
+          y: 80,
+          width: 360,
+          height: 360,
+          originalWidth: 1024,
+          originalHeight: 1024,
+          zIndex: 3,
+          sourceType: 'generated',
+          prompt: '明亮主视觉',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'task-1',
+        },
+        {
+          layerId: 'layer-failed',
+          resourceId: 'resource-failed',
+          title: '失败图',
+          src: '/missing.png',
+          x: 90,
+          y: 100,
+          width: 120,
+          height: 120,
+          originalWidth: 120,
+          originalHeight: 120,
+          zIndex: 4,
+          sourceType: 'generated',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-data-a',
+          folderId: 'project',
+          label: '素材/A',
+          imageSrc: 'data:image/png;base64,YQ==',
+          width: 640,
+          height: 440,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async (url: string) => {
+      if (url === '/generated-ok.png') {
+        return new Response(new Blob(['generated'], { type: 'image/png' }));
+      }
+      return new Response(null, { status: 404 });
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+    const originalCreateObjectUrl = URL.createObjectURL;
+    const originalRevokeObjectUrl = URL.revokeObjectURL;
+    const originalAnchorClick = HTMLAnchorElement.prototype.click;
+    let exportedBlob: Blob | null = null;
+    let downloadName = '';
+    URL.createObjectURL = vi.fn((blob: Blob) => {
+      exportedBlob = blob;
+      return 'blob:editor-export';
+    });
+    URL.revokeObjectURL = vi.fn();
+    HTMLAnchorElement.prototype.click = vi.fn(function click(
+      this: HTMLAnchorElement,
+    ) {
+      downloadName = this.download;
+    });
+
+    try {
+      render(<ImageCanvasEditorView />);
+
+      await screen.findByRole('heading', { name: '导出项目' });
+      await waitFor(() => {
+        expect(
+          (
+            screen.getByRole('button', {
+              name: '下载画布素材',
+            }) as HTMLButtonElement
+          ).disabled,
+        ).toBe(false);
+      });
+      fireEvent.click(screen.getByRole('button', { name: '下载画布素材' }));
+
+      await waitFor(() => {
+        expect(exportedBlob).toBeTruthy();
+      });
+      expect(downloadName).toMatch(/^导出项目-画布素材-\d{8}\.zip$/u);
+
+      const zip = await JSZip.loadAsync(exportedBlob!);
+      expect(zip.file('导出项目-画布素材/images/001-素材 A.png')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/images/002-生成图.png')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/images/003-失败图.png')).toBeNull();
+
+      const metadata = JSON.parse(
+        await readZipText(zip, '导出项目-画布素材/metadata.json'),
+      );
+      expect(metadata.projectId).toBe('editor-project-export');
+      expect(metadata.layers).toHaveLength(4);
+      expect(metadata.layers[0].file).toBe('images/001-素材 A.png');
+      expect(metadata.layers[1].file).toBe('images/001-素材 A.png');
+      expect(metadata.layers[0].canvas.hidden).toBe(true);
+      expect(metadata.layers[0].canvas.locked).toBe(true);
+      expect(metadata.layers[0].canvas.flipX).toBe(true);
+      expect(metadata.layers[0].canvas.groupId).toBe('group-a');
+      expect(metadata.layers[2].sourceType).toBe('generated');
+      expect(metadata.layers[2].prompt).toBe('明亮主视觉');
+      expect(metadata.layers[3].file).toBeNull();
+      expect(metadata.layers[3].exportError).toContain('404');
+      expect(metadata.failedImages).toHaveLength(1);
+      expect(
+        await readZipText(zip, '导出项目-画布素材/manifest.txt'),
+      ).toContain('失败素材数量：1');
+      expect(screen.getByText('部分素材未能导出')).toBeTruthy();
+    } finally {
+      globalThis.fetch = originalFetch;
+      URL.createObjectURL = originalCreateObjectUrl;
+      URL.revokeObjectURL = originalRevokeObjectUrl;
+      HTMLAnchorElement.prototype.click = originalAnchorClick;
+    }
+  });
+
+  it('disables the canvas asset export entry when there are no valid layers', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-empty-export',
+      title: '空导出项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByRole('heading', { name: '空导出项目' });
+    expect(
+      (
+        screen.getByRole('button', {
+          name: '下载画布素材',
+        }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(true);
+  });
+
+  it('shows image resolution on hover and opens the crop-expand panel after selecting a layer', () => {
+    render(<ImageCanvasEditorView />);
+
+    const canvasImage = screen.getByAltText('画布图片：拼图素材');
+    fireEvent.mouseEnter(canvasImage.closest('button')!);
+
+    const sizeBadge = screen.getByText('640 x 640 px');
+    expect(sizeBadge.className).toContain('rounded-full');
+    expect(sizeBadge.className).toContain('image-canvas-editor__size-badge');
+
+    fireEvent.pointerDown(canvasImage.closest('button')!, {
+      button: 0,
+      pointerId: 1,
+      clientX: 120,
+      clientY: 120,
+    });
+
+    const cropButton = screen.getByRole('button', { name: '裁扩按钮' });
+    fireEvent.pointerDown(cropButton, {
+      button: 0,
+      pointerId: 2,
+      clientX: 120,
+      clientY: 96,
+    });
+    fireEvent.click(cropButton);
+
+    expect(screen.getByRole('dialog', { name: '裁扩图片' })).toBeTruthy();
+    expect(
+      screen.getByRole('button', { name: '自由比例' }).getAttribute(
+        'aria-pressed',
+      ),
+    ).toBe('true');
+    expect(screen.queryByLabelText('裁扩左')).toBeNull();
+    expect(screen.getByRole('toolbar', { name: '图片工具栏' })).toBeTruthy();
+  });
+
+  it('opens image info for uploaded canvas images without generated edit tools', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 61,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+
+    const infoButton = screen.getByRole('button', {
+      name: '查看拼图素材图片信息',
+    });
+    expect(infoButton.className).toContain(
+      'image-canvas-editor__metadata-corner',
+    );
+    fireEvent.click(infoButton);
+
+    const infoPanel = screen.getByRole('dialog', { name: '图片信息' });
+    expect(within(infoPanel).getByText('图片类型')).toBeTruthy();
+    expect(within(infoPanel).getByText('上传图片')).toBeTruthy();
+    expect(within(infoPanel).getByText('生成输入')).toBeTruthy();
+    expect(
+      infoPanel.querySelector('.image-canvas-editor__metadata-inputs')
+        ?.textContent,
+    ).toBe('-');
+    expect(within(infoPanel).queryByText('Prompt')).toBeNull();
+    expect(within(infoPanel).getByText('Model')).toBeTruthy();
+    expect(within(infoPanel).queryByText('Size')).toBeNull();
+    expect(within(infoPanel).getByText('Resolution')).toBeTruthy();
+    expect(within(infoPanel).getByText('640 x 640 px')).toBeTruthy();
+    expect(
+      within(infoPanel).queryByRole('button', { name: '复制Prompt' }),
+    ).toBeNull();
+    expect(screen.getByRole('button', { name: '改造' })).toBeTruthy();
+  });
+
+  it('hydrates canvas images from Resolution instead of saved Size', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-resolution',
+      title: '原分辨率画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-resolution',
+          resourceId: 'resource-resolution',
+          title: '旧布局图片',
+          src: 'data:image/png;base64,cmVzb2x1dGlvbg==',
+          x: 120,
+          y: 140,
+          width: 320,
+          height: 240,
+          originalWidth: 1536,
+          originalHeight: 1024,
+          zIndex: 2,
+          sourceType: 'generated',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'resolution-task-1',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-16T00:00:00.000Z',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const canvasImage = await screen.findByAltText('画布图片：旧布局图片');
+    const canvasLayer = canvasImage.closest('button') as HTMLElement;
+    expect(Number.parseFloat(canvasLayer.style.width)).toBe(1536);
+    expect(Number.parseFloat(canvasLayer.style.height)).toBe(1024);
+
+    fireEvent.mouseEnter(canvasLayer);
+    expect(screen.getByText('1536 x 1024 px')).toBeTruthy();
+    fireEvent.click(
+      screen.getAllByRole('button', { name: '查看旧布局图片图片信息' })[0]!,
+    );
+    const infoPanel = screen.getByRole('dialog', { name: '图片信息' });
+    expect(within(infoPanel).queryByText('Size')).toBeNull();
+    expect(within(infoPanel).getByText('Resolution')).toBeTruthy();
+    expect(within(infoPanel).getByText('1536 x 1024 px')).toBeTruthy();
+  });
+
+  it('downloads the selected layer from the floating toolbar', () => {
+    let downloadName = '';
+    let downloadHref = '';
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(
+      function click(this: HTMLAnchorElement) {
+        downloadName = this.download;
+        downloadHref = this.href;
+      },
+    );
+    render(<ImageCanvasEditorView />);
+
+    expect(screen.getByAltText('画布图片：拼图素材')).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 51,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    fireEvent.click(screen.getByRole('button', { name: '下载按钮' }));
+
+    expect(downloadName).toBe('拼图素材.webp');
+    expect(downloadHref).toContain('/creation-type-references/puzzle.webp');
+    expect(screen.getByAltText('画布图片：拼图素材')).toBeTruthy();
+    expect(screen.getByAltText('画布图片：大鱼素材')).toBeTruthy();
+  });
+
+  it('deletes the selected layer with Backspace when focus is outside text inputs', async () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(screen.getByAltText('画布图片：拼图素材')).toBeTruthy();
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 52,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    await act(async () => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(screen.queryByAltText('画布图片：拼图素材')).toBeNull();
+    expect(screen.getByAltText('画布图片：大鱼素材')).toBeTruthy();
+  });
+
+  it('opens the matching audio generation panel when remodeling an existing sound effect layer', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-audio-remodel',
+      title: '音频改造画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-sound-effect',
+          resourceId: 'resource-sound-effect',
+          title: '游戏音效',
+          src: '/generated-character-drafts/editor-audios/sound.wav',
+          mediaType: 'audio',
+          assetKind: 'sound-effect',
+          x: 120,
+          y: 140,
+          width: 420,
+          height: 120,
+          originalWidth: 420,
+          originalHeight: 120,
+          zIndex: 2,
+          sourceType: 'generated',
+          prompt: '金币跳出音',
+          model: 'audio1.0',
+          generationInputs: {
+            fields: [
+              { title: '音效提示词', value: '金币跳出音' },
+              { title: 'model', value: 'audio1.0' },
+              { title: 'duration', value: '8秒' },
+            ],
+            references: [
+              { label: '历史参考图', src: '/creation-type-references/puzzle.webp' },
+            ],
+          },
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-19T00:00:00.000Z',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const audioLayer = await screen.findByRole('button', {
+      name: '选择游戏音效',
+    });
+    fireEvent.pointerDown(audioLayer, {
+      button: 0,
+      pointerId: 54,
+      clientX: 160,
+      clientY: 180,
+    });
+    fireEvent.click(screen.getByRole('button', { name: '改造' }));
+
+    const panel = screen.getByRole('dialog', { name: '生成游戏音效' });
+    expect(within(panel).getByDisplayValue('金币跳出音')).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', { name: '音效时长 8秒' }),
+    ).toBeTruthy();
+    expect(panel.querySelector('.image-canvas-editor__reference-strip')).toBeNull();
+  });
+
+  it('deletes the selected audio layer with Backspace from the audio control focus', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-audio-delete',
+      title: '音频删除画布',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-audio',
+          resourceId: 'resource-audio',
+          title: '背景音乐',
+          src: '/generated-character-drafts/editor-audios/bgm.mp3',
+          mediaType: 'audio',
+          assetKind: 'background-music',
+          x: 120,
+          y: 140,
+          width: 420,
+          height: 120,
+          originalWidth: 420,
+          originalHeight: 120,
+          zIndex: 2,
+          sourceType: 'generated',
+        },
+        {
+          layerId: 'layer-reference',
+          resourceId: 'resource-reference',
+          title: '参考图片',
+          src: '/creation-type-references/puzzle.webp',
+          x: 620,
+          y: 140,
+          width: 320,
+          height: 320,
+          originalWidth: 320,
+          originalHeight: 320,
+          zIndex: 1,
+          sourceType: 'uploaded',
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-18T00:00:00.000Z',
+    });
+    render(<ImageCanvasEditorView />);
+
+    const audioControl = await screen.findByLabelText('画布音频：背景音乐');
+    fireEvent.pointerDown(audioControl, {
+      button: 0,
+      pointerId: 53,
+      clientX: 160,
+      clientY: 180,
+    });
+    await act(async () => {
+      fireEvent.keyDown(audioControl, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(screen.queryByLabelText('画布音频：背景音乐')).toBeNull();
+    expect(screen.getByAltText('画布图片：参考图片')).toBeTruthy();
+  });
+
+  it('blocks the browser context menu inside the editor workspace', () => {
+    render(<ImageCanvasEditorView />);
+
+    const editor = screen.getByRole('region', { name: '图片画布编辑器' });
+    const contextMenuEvent = new MouseEvent('contextmenu', {
+      bubbles: true,
+      cancelable: true,
+    });
+    const wasNotCanceled = editor.dispatchEvent(contextMenuEvent);
+
+    expect(wasNotCanceled).toBe(false);
+    expect(contextMenuEvent.defaultPrevented).toBe(true);
+  });
+
+  it('shows the blank canvas context menu with paste disabled, zoom, and fit all', () => {
+    render(<ImageCanvasEditorView />);
+
+    const viewport = screen.getByLabelText('画布工作区');
+    fireEvent.contextMenu(viewport, {
+      clientX: 320,
+      clientY: 220,
+    });
+
+    const menu = screen.getByRole('menu', { name: '画布右键菜单' });
+    expect(
+      (
+        within(menu).getByRole('menuitem', {
+          name: '粘贴',
+        }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(true);
+    expect(within(menu).getByRole('menuitem', { name: '放大' })).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '显示画布所有元素' }),
+    ).toBeTruthy();
+  });
+
+  it('keeps right-clicking a canvas layer from falling through to blank pan menu handling', () => {
+    render(<ImageCanvasEditorView />);
+
+    const layerButton = screen
+      .getByAltText('画布图片：拼图素材')
+      .closest('button')!;
+    const rightPointerDown = new MouseEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button: 2,
+      clientX: 510,
+      clientY: 330,
+    });
+
+    const wasNotCanceled = layerButton.dispatchEvent(rightPointerDown);
+
+    expect(wasNotCanceled).toBe(true);
+    expect(rightPointerDown.defaultPrevented).toBe(false);
+
+    fireEvent.contextMenu(layerButton, {
+      clientX: 510,
+      clientY: 330,
+    });
+
+    expect(screen.getByRole('menu', { name: '图片功能面板' })).toBeTruthy();
+    expect(screen.getByRole('menuitem', { name: '创建副本' })).toBeTruthy();
+  });
+
+  it('copies, cuts, and pastes layers from the context menus', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.contextMenu(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        clientX: 510,
+        clientY: 330,
+      },
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '复制' }));
+
+    fireEvent.contextMenu(screen.getByLabelText('画布工作区'), {
+      clientX: 360,
+      clientY: 240,
+    });
+    const copyPasteMenu = screen.getByRole('menu', { name: '画布右键菜单' });
+    expect(
+      (
+        within(copyPasteMenu).getByRole('menuitem', {
+          name: '粘贴',
+        }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(false);
+    fireEvent.click(
+      within(copyPasteMenu).getByRole('menuitem', { name: '粘贴' }),
+    );
+    expect(screen.getAllByAltText(/画布图片：拼图素材/u)).toHaveLength(2);
+
+    fireEvent.contextMenu(
+      screen.getByAltText('画布图片：大鱼素材').closest('button')!,
+      {
+        clientX: 950,
+        clientY: 380,
+      },
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '剪切' }));
+    expect(screen.queryByAltText('画布图片：大鱼素材')).toBeNull();
+
+    fireEvent.contextMenu(screen.getByLabelText('画布工作区'), {
+      clientX: 420,
+      clientY: 260,
+    });
+    fireEvent.click(screen.getByRole('menuitem', { name: '粘贴' }));
+    expect(screen.getByAltText('画布图片：大鱼素材')).toBeTruthy();
+  });
+
+  it('handles layer context menu duplicate, ordering, hide, lock, flip, group, ungroup, and delete', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const firstLayer = screen
+      .getByAltText('画布图片：拼图素材')
+      .closest('button')!;
+    fireEvent.contextMenu(firstLayer, { clientX: 510, clientY: 330 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '创建副本' }));
+    expect(screen.getAllByAltText(/画布图片：拼图素材/u)).toHaveLength(2);
+
+    const copiedLayer = screen
+      .getAllByAltText(/画布图片：拼图素材/u)[1]!
+      .closest('button')!;
+    fireEvent.contextMenu(copiedLayer, { clientX: 540, clientY: 360 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '水平翻转' }));
+    expect(
+      (screen.getAllByAltText(/画布图片：拼图素材/u)[1] as HTMLElement).style
+        .transform,
+    ).toBe('scale(-1, 1)');
+
+    fireEvent.contextMenu(copiedLayer, { clientX: 540, clientY: 360 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '锁定' }));
+    await waitFor(() => {
+      expect(copiedLayer.className).toContain(
+        'image-canvas-editor__layer--locked',
+      );
+    });
+
+    fireEvent.contextMenu(copiedLayer, { clientX: 540, clientY: 360 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '隐藏' }));
+    expect(screen.getAllByAltText(/画布图片：拼图素材/u)).toHaveLength(1);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+    expect(screen.getByText(/已隐藏/u)).toBeTruthy();
+    fireEvent.contextMenu(
+      screen.getByText(/已隐藏/u).closest('.image-canvas-editor__layer-row')!,
+      {
+        clientX: 80,
+        clientY: 220,
+      },
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: '显示' }));
+    expect(screen.getAllByAltText(/画布图片：拼图素材/u)).toHaveLength(2);
+
+    const bigFishLayer = screen
+      .getByAltText('画布图片：大鱼素材')
+      .closest('button')!;
+    fireEvent.contextMenu(bigFishLayer, { clientX: 950, clientY: 380 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '置于顶层' }));
+    expect(Number.parseInt(bigFishLayer.style.zIndex, 10)).toBeGreaterThan(2);
+
+    fireEvent.contextMenu(bigFishLayer, { clientX: 950, clientY: 380 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '下移一层' }));
+    expect(Number.parseInt(bigFishLayer.style.zIndex, 10)).toBeGreaterThan(0);
+
+    fireEvent.keyDown(window, { key: 'Shift', code: 'ShiftLeft' });
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 181,
+        clientX: 520,
+        clientY: 380,
+        shiftKey: true,
+      },
+    );
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 181,
+      clientX: 520,
+      clientY: 380,
+    });
+    fireEvent.keyUp(window, { key: 'Shift', code: 'ShiftLeft' });
+    fireEvent.contextMenu(bigFishLayer, { clientX: 950, clientY: 380 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '创建组' }));
+    await waitFor(() => {
+      expect(screen.getAllByText(/已打组/u).length).toBeGreaterThan(0);
+    });
+
+    fireEvent.contextMenu(bigFishLayer, { clientX: 950, clientY: 380 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '解除组' }));
+    await waitFor(() => {
+      expect(screen.queryByText(/已打组/u)).toBeNull();
+    });
+
+    fireEvent.contextMenu(bigFishLayer, { clientX: 950, clientY: 380 });
+    fireEvent.click(screen.getByRole('menuitem', { name: '删除' }));
+    expect(screen.queryByAltText('画布图片：大鱼素材')).toBeNull();
+  });
+
+  it('switches the shared sidebar between assets and layers', () => {
+    render(<ImageCanvasEditorView />);
+
+    const sidebar = screen.getByRole('complementary', { name: '图片资源栏' });
+    expect(within(sidebar).getByText('素材')).toBeTruthy();
+    expect(within(sidebar).queryByText('已生成文件')).toBeNull();
+    expect(within(sidebar).queryByText('图层')).toBeNull();
+    expect(screen.queryByRole('toolbar', { name: '画布主工具栏' })).toBeNull();
+    expect(
+      screen.queryByRole('complementary', { name: '图层面板' }),
+    ).toBeNull();
+    expect(screen.queryByRole('dialog', { name: '已生成文件' })).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+    const layersPanel = screen.getByRole('complementary', {
+      name: '图片资源栏',
+    });
+    expect(
+      within(layersPanel).getByRole('button', { name: '选择图层拼图素材' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '选择图层大鱼素材' }));
+
+    expect(screen.getByRole('toolbar', { name: '图片工具栏' })).toBeTruthy();
+    expect(
+      screen.getByRole('button', { name: '查看大鱼素材图片信息' }),
+    ).toBeTruthy();
+    expect(screen.getByRole('button', { name: '改造' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '打开素材' }));
+
+    expect(screen.getByRole('button', { name: '添加拼图素材' })).toBeTruthy();
+  });
+
+  it('adds assets from the sidebar and supports zoom buttons', () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 100%' }).className,
+    ).toContain('platform-inline-option-button');
+
+    fireEvent.click(screen.getByRole('button', { name: '当前缩放比例 100%' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '放大' }));
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 116%' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(
+      screen.getByRole('complementary', { name: '图片资源栏' }),
+    ).toBeTruthy();
+  });
+
+  it('saves canvas layout without embedding image payloads in layer snapshots', async () => {
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        {
+          assetId: 'asset-data-heavy',
+          folderId: 'project',
+          label: '大图素材',
+          imageSrc: 'data:image/png;base64,'.concat('a'.repeat(4000)),
+          width: 1024,
+          height: 768,
+          sourceType: 'uploaded',
+        },
+      ],
+    });
+    render(<ImageCanvasEditorView />);
+
+    await screen.findByRole('button', { name: '添加大图素材' });
+    fireEvent.click(screen.getByRole('button', { name: '添加大图素材' }));
+
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalled();
+    });
+    const lastLayout = saveEditorProjectLayoutMock.mock.calls.at(-1)?.[1];
+
+    expect(lastLayout.layers).toEqual(
+      expect.arrayContaining([
+        expect.not.objectContaining({
+          src: expect.stringMatching(/^data:image/u),
+        }),
+      ]),
+    );
+    expect(lastLayout.layers).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          sourceAssetId: 'asset-data-heavy',
+        }),
+      ]),
+    );
+  });
+
+  it('saves manually selected layer tags in the canvas layout', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const layerButton = await screen.findByRole('button', {
+      name: '选择拼图素材',
+    });
+    fireEvent.click(
+      within(layerButton).getByRole('button', { name: '素材标签：未知' }),
+    );
+    fireEvent.click(
+      within(screen.getByRole('menu', { name: '选择素材标签' })).getByRole(
+        'menuitem',
+        { name: '角色' },
+      ),
+    );
+
+    await screen.findByRole('button', { name: '素材标签：角色' });
+
+    await waitFor(() => {
+      expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          imageSrc: '/creation-type-references/puzzle.webp',
+          assetKind: 'character',
+        }),
+      );
+    });
+    await waitFor(() => {
+      const savedLayout = saveEditorProjectLayoutMock.mock.calls
+        .map((call) => call[1])
+        .find((layout) =>
+          layout.layers.some(
+            (layer: { resourceId?: unknown; title?: unknown }) =>
+              layer.title === '拼图素材' &&
+              layer.resourceId === 'resource-editor-project-default-640',
+          ),
+        );
+
+      expect(savedLayout).toBeTruthy();
+      expect(savedLayout.layers).toEqual(
+        expect.arrayContaining([
+          expect.not.objectContaining({
+            title: '拼图素材',
+            assetKind: expect.anything(),
+          }),
+        ]),
+      );
+    });
+  });
+
+  it('offers Lovart-style zoom menu commands', async () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '当前缩放比例 100%' }));
+
+    expect(screen.getByRole('menu', { name: '缩放菜单' })).toBeTruthy();
+    expect(
+      screen.getByRole('menuitem', { name: '显示画布所有元素' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '缩放至100%' }));
+    expect(
+      screen.getByRole('button', { name: /当前缩放比例 \d+%/u }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '当前缩放比例 100%' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '缩放至50%' }));
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 50%' }),
+    ).toBeTruthy();
+  });
+
+  it('shows the Lovart-style minimap and canvas background settings panel', () => {
+    render(<ImageCanvasEditorView />);
+
+    const viewport = screen.getByLabelText('画布工作区');
+    const panelToolbar = screen.getByRole('toolbar', { name: '画布面板入口' });
+    const backgroundButton = within(panelToolbar).getByRole('button', {
+      name: '画布背景色',
+    });
+
+    expect(screen.getByRole('button', { name: '画布小地图' })).toBeTruthy();
+    expect(backgroundButton.className).toContain('platform-icon-button');
+    expect(
+      within(panelToolbar).getByRole('button', { name: '切换小地图' }),
+    ).toBeTruthy();
+
+    fireEvent.click(backgroundButton);
+    const settingsPanel = screen.getByRole('dialog', {
+      name: '画布背景设置',
+    });
+    expect(within(settingsPanel).getByText('画布背景')).toBeTruthy();
+    expect(within(settingsPanel).getByLabelText('画布背景色相')).toBeTruthy();
+    expect(
+      within(settingsPanel).getByLabelText('画布背景十六进制颜色'),
+    ).toBeTruthy();
+
+    fireEvent.click(
+      within(settingsPanel).getByRole('button', { name: '暖灰' }),
+    );
+
+    expect((viewport as HTMLElement).style.backgroundColor).toBe(
+      'rgb(243, 240, 234)',
+    );
+
+    fireEvent.change(within(settingsPanel).getByLabelText('自定义画布背景色'), {
+      target: { value: '#ffffff' },
+    });
+    expect((viewport as HTMLElement).style.backgroundColor).toBe(
+      'rgb(255, 255, 255)',
+    );
+
+    const hexInput =
+      within(settingsPanel).getByLabelText('画布背景十六进制颜色');
+    fireEvent.change(hexInput, { target: { value: '#abc' } });
+    expect((hexInput as HTMLInputElement).value).toBe('#aabbcc');
+    expect((viewport as HTMLElement).style.backgroundColor).toBe(
+      'rgb(170, 187, 204)',
+    );
+
+    fireEvent.change(hexInput, { target: { value: '#not-a-color' } });
+    expect((hexInput as HTMLInputElement).value).toBe('#not-a-color');
+    expect((viewport as HTMLElement).style.backgroundColor).toBe(
+      'rgb(170, 187, 204)',
+    );
+
+    fireEvent.click(
+      within(settingsPanel).getByRole('button', { name: '恢复默认' }),
+    );
+    expect((viewport as HTMLElement).style.backgroundColor).toBe(
+      'rgb(248, 250, 252)',
+    );
+
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(screen.queryByRole('dialog', { name: '画布背景设置' })).toBeNull();
+
+    fireEvent.click(
+      within(panelToolbar).getByRole('button', { name: '切换小地图' }),
+    );
+    expect(screen.queryByRole('button', { name: '画布小地图' })).toBeNull();
+  });
+
+  it('resets the canvas view without forwarding the click event to fit layers', () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(() => {
+      fireEvent.click(screen.getByRole('button', { name: '重置画布视图' }));
+    }).not.toThrow();
+  });
+
+  it('uses normal wheel for vertical canvas scroll and ctrl wheel for zoom', () => {
+    render(<ImageCanvasEditorView />);
+
+    const viewport = screen.getByLabelText('画布工作区');
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 100%' }),
+    ).toBeTruthy();
+
+    fireEvent.wheel(viewport, { deltaY: 120, clientX: 400, clientY: 280 });
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 100%' }),
+    ).toBeTruthy();
+
+    fireEvent.wheel(viewport, {
+      deltaY: -120,
+      ctrlKey: true,
+      clientX: 400,
+      clientY: 280,
+    });
+    expect(
+      screen.getByRole('button', { name: '当前缩放比例 110%' }),
+    ).toBeTruthy();
+
+    const ctrlWheelEvent = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      ctrlKey: true,
+      deltaY: -120,
+      clientX: 400,
+      clientY: 280,
+    });
+    viewport.dispatchEvent(ctrlWheelEvent);
+    expect(ctrlWheelEvent.defaultPrevented).toBe(true);
+  });
+
+  it('selects multiple canvas layers with shift click', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const firstLayer = screen
+      .getByAltText('画布图片：拼图素材')
+      .closest('button')!;
+    const secondLayer = screen
+      .getByAltText('画布图片：大鱼素材')
+      .closest('button')!;
+
+    fireEvent.pointerDown(firstLayer, {
+      button: 0,
+      pointerId: 81,
+      clientX: 120,
+      clientY: 120,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 81,
+      clientX: 120,
+      clientY: 120,
+    });
+    await waitFor(() => {
+      expect(
+        screen.getByAltText('画布图片：拼图素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+    });
+    fireEvent.keyDown(window, { key: 'Shift', code: 'ShiftLeft' });
+    fireEvent.pointerDown(secondLayer, {
+      button: 0,
+      pointerId: 82,
+      clientX: 520,
+      clientY: 180,
+      shiftKey: true,
+    });
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 82,
+      clientX: 520,
+      clientY: 180,
+    });
+    fireEvent.keyUp(window, { key: 'Shift', code: 'ShiftLeft' });
+
+    await waitFor(() => {
+      expect(
+        screen.getByAltText('画布图片：拼图素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+      expect(
+        screen.getByAltText('画布图片：大鱼素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+    });
+  });
+
+  it('drags the minimap to move the canvas viewport', () => {
+    render(<ImageCanvasEditorView />);
+
+    const minimap = screen.getByRole('button', { name: '画布小地图' });
+    vi.spyOn(minimap, 'getBoundingClientRect').mockReturnValue({
+      x: 0,
+      y: 0,
+      left: 0,
+      top: 0,
+      right: 132,
+      bottom: 84,
+      width: 132,
+      height: 84,
+      toJSON: () => ({}),
+    });
+    dispatchPointerEvent(minimap, 'pointerdown', {
+      button: 0,
+      pointerId: 71,
+      clientX: 120,
+      clientY: 72,
+    });
+
+    const firstLayer = screen
+      .getByAltText('画布图片：拼图素材')
+      .closest('button')!;
+    expect(Number.parseFloat((firstLayer as HTMLElement).style.left)).toBe(470);
+    expect(screen.getByRole('button', { name: '画布小地图' })).toBeTruthy();
+  });
+
+  it('keeps minimap drag direction stable after pausing and reversing', () => {
+    render(<ImageCanvasEditorView />);
+
+    const minimap = screen.getByRole('button', { name: '画布小地图' });
+    vi.spyOn(minimap, 'getBoundingClientRect').mockReturnValue({
+      x: 0,
+      y: 0,
+      left: 0,
+      top: 0,
+      right: 132,
+      bottom: 84,
+      width: 132,
+      height: 84,
+      toJSON: () => ({}),
+    });
+    const world = screen
+      .getByLabelText('画布工作区')
+      .querySelector('.image-canvas-editor__world') as HTMLElement;
+    const readTranslateX = () => {
+      const match = /translate\(([-\d.]+)px,/u.exec(world.style.transform);
+      return match ? Number(match[1]) : 0;
+    };
+
+    dispatchPointerEvent(minimap, 'pointerdown', {
+      button: 0,
+      pointerId: 72,
+      clientX: 60,
+      clientY: 42,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      button: 0,
+      pointerId: 72,
+      clientX: 120,
+      clientY: 42,
+    });
+    const translateAfterRightDrag = readTranslateX();
+
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      button: 0,
+      pointerId: 72,
+      clientX: 90,
+      clientY: 42,
+    });
+
+    expect(readTranslateX()).toBeGreaterThan(translateAfterRightDrag);
+  });
+
+  it('persists layer groups in the canvas layer snapshot', async () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 90,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 90,
+      clientX: 120,
+      clientY: 120,
+    });
+    await waitFor(() => {
+      expect(
+        screen.getByAltText('画布图片：拼图素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+    });
+    fireEvent.keyDown(window, { key: 'Shift', code: 'ShiftLeft' });
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：大鱼素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 91,
+        clientX: 520,
+        clientY: 180,
+        shiftKey: true,
+      },
+    );
+    fireEvent.pointerUp(screen.getByLabelText('画布工作区'), {
+      pointerId: 91,
+      clientX: 520,
+      clientY: 180,
+    });
+    fireEvent.keyUp(window, { key: 'Shift', code: 'ShiftLeft' });
+    await waitFor(() => {
+      expect(
+        screen.getByAltText('画布图片：拼图素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+      expect(
+        screen.getByAltText('画布图片：大鱼素材').closest('button')?.className,
+      ).toContain('image-canvas-editor__layer--selected');
+    });
+    fireEvent.click(screen.getByRole('button', { name: '图层打组' }));
+
+    await waitFor(() => {
+      expect(screen.getAllByText(/已打组/u)).toHaveLength(2);
+    });
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              title: '拼图素材',
+              groupId: expect.stringMatching(/^layer-group-/u),
+            }),
+            expect.objectContaining({
+              title: '大鱼素材',
+              groupId: expect.stringMatching(/^layer-group-/u),
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('switches tools and restores the previous tool after holding Space', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    const selectTool = within(bottomToolbar).getByRole('button', {
+      name: '选择工具',
+    });
+    const handTool = within(bottomToolbar).getByRole('button', {
+      name: '抓手工具',
+    });
+
+    expect(selectTool.getAttribute('aria-pressed')).toBe('true');
+
+    fireEvent.keyDown(window, { code: 'Space', key: ' ' });
+    expect(handTool.getAttribute('aria-pressed')).toBe('true');
+
+    fireEvent.keyUp(window, { code: 'Space', key: ' ' });
+    expect(selectTool.getAttribute('aria-pressed')).toBe('true');
+  });
+
+  it('switches away from hand tool from the bottom toolbar', async () => {
+    const user = userEvent.setup();
+    render(<ImageCanvasEditorView />);
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    const handTool = within(bottomToolbar).getByRole('button', {
+      name: '抓手工具',
+    });
+    const selectTool = within(bottomToolbar).getByRole('button', {
+      name: '选择工具',
+    });
+
+    await user.click(handTool);
+    expect(handTool.getAttribute('aria-pressed')).toBe('true');
+
+    await user.click(selectTool);
+    expect(selectTool.getAttribute('aria-pressed')).toBe('true');
+    expect(handTool.getAttribute('aria-pressed')).toBe('false');
+  });
+
+  it('pans with the middle mouse button without leaving select mode', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const viewport = screen.getByLabelText('画布工作区');
+    const middlePointerDown = new MouseEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button: 1,
+      buttons: 4,
+      clientX: 260,
+      clientY: 220,
+    });
+    Object.defineProperty(middlePointerDown, 'pointerId', { value: 11 });
+    fireEvent(viewport, middlePointerDown);
+
+    await waitFor(() => {
+      expect(viewport.className).toContain(
+        'image-canvas-editor__viewport--panning',
+      );
+    });
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    expect(
+      within(bottomToolbar)
+        .getByRole('button', { name: '选择工具' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+  });
+
+  it('shows snap guides when dragging a layer near another layer alignment', async () => {
+    render(<ImageCanvasEditorView />);
+
+    const puzzleLayer = screen
+      .getByAltText('画布图片：拼图素材')
+      .closest('button')!;
+    dispatchPointerEvent(puzzleLayer, 'pointerdown', {
+      button: 0,
+      pointerId: 21,
+      clientX: 120,
+      clientY: 120,
+    });
+    dispatchPointerEvent(screen.getByLabelText('画布工作区'), 'pointermove', {
+      pointerId: 21,
+      clientX: -60,
+      clientY: 180,
+    });
+
+    expect(
+      screen.getByTestId('image-canvas-editor-snap-guide-vertical'),
+    ).toBeTruthy();
+    expect(
+      screen.getByTestId('image-canvas-editor-snap-guide-horizontal'),
+    ).toBeTruthy();
+  });
+
+  it('can switch tools after a layer drag started without pointer release', async () => {
+    const user = userEvent.setup();
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.pointerDown(
+      screen.getByAltText('画布图片：拼图素材').closest('button')!,
+      {
+        button: 0,
+        pointerId: 41,
+        clientX: 120,
+        clientY: 120,
+      },
+    );
+    fireEvent.pointerMove(screen.getByLabelText('画布工作区'), {
+      pointerId: 41,
+      clientX: 220,
+      clientY: 160,
+    });
+
+    const bottomToolbar = screen.getByRole('toolbar', { name: 'AI画布工具栏' });
+    const handTool = within(bottomToolbar).getByRole('button', {
+      name: '抓手工具',
+    });
+    await user.click(handTool);
+
+    expect(handTool.getAttribute('aria-pressed')).toBe('true');
+    expect(
+      screen.queryByTestId('image-canvas-editor-snap-guide-vertical'),
+    ).toBeNull();
+  });
+
+  it('undoes and redoes canvas layer changes from the panel controls', () => {
+    render(<ImageCanvasEditorView />);
+
+    expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(
+      'disabled',
+      true,
+    );
+    expect(screen.getByRole('button', { name: '重做' })).toHaveProperty(
+      'disabled',
+      true,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '撤销' })).toHaveProperty(
+      'disabled',
+      false,
+    );
+    fireEvent.click(screen.getByRole('button', { name: '撤销' }));
+
+    expect(screen.queryByAltText('画布图片：声浪素材')).toBeNull();
+    expect(screen.getByRole('button', { name: '重做' })).toHaveProperty(
+      'disabled',
+      false,
+    );
+    fireEvent.click(screen.getByRole('button', { name: '重做' }));
+
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+  });
+
+  it('supports undo and redo keyboard shortcuts inside the editor', () => {
+    render(<ImageCanvasEditorView />);
+
+    fireEvent.click(screen.getByRole('button', { name: '添加声浪素材' }));
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+
+    fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
+    expect(screen.queryByAltText('画布图片：声浪素材')).toBeNull();
+
+    fireEvent.keyDown(window, {
+      key: 'Z',
+      code: 'KeyZ',
+      ctrlKey: true,
+      shiftKey: true,
+    });
+    expect(screen.getByAltText('画布图片：声浪素材')).toBeTruthy();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
new file mode 100644
index 000000000..48b2d330a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -0,0 +1,1160 @@
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import {
+  createEditorAsset,
+  createEditorProjectResource,
+  type EditorAssetSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import { useAuthUi } from '../auth/AuthUiContext';
+import { PlatformDangerConfirmDialog } from '../common/PlatformDangerConfirmDialog';
+import {
+  canvasAssetKindOrNull,
+  generationInputsOrNull,
+  resolveContextMenuPosition,
+} from './ImageCanvasEditorModel';
+import { ImageCanvasEditorShellView } from './ImageCanvasEditorShellView';
+import type {
+  AssetPointerDragState,
+  CanvasAssetKind,
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  CanvasViewport,
+  ImageContextMenuState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import { getEditorUploadAccept } from './ImageCanvasFileModel';
+import { isCanvasGenerationComposerVisible } from './ImageCanvasOverlayModel';
+import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
+import { useCanvasHistory } from './useCanvasHistory';
+import {
+  useImageCanvasAssetCanvasBridge,
+  useImageCanvasAssetLayerCleanup,
+} from './useImageCanvasAssetCanvasBridge';
+import { useImageCanvasAssetExportWorkflow } from './useImageCanvasAssetExportWorkflow';
+import { useImageCanvasAssetLibrary } from './useImageCanvasAssetLibrary';
+import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
+import { useImageCanvasGenerationSurface } from './useImageCanvasGenerationSurface';
+import { useImageCanvasKeyboardShortcuts } from './useImageCanvasKeyboardShortcuts';
+import { useImageCanvasLayerCommands } from './useImageCanvasLayerCommands';
+import { useImageCanvasProjectPersistence } from './useImageCanvasProjectPersistence';
+import { useImageCanvasStageController } from './useImageCanvasStageController';
+import { useImageCanvasStageInteractions } from './useImageCanvasStageInteractions';
+import { useImageCanvasUploadWorkflow } from './useImageCanvasUploadWorkflow';
+import {
+  DEFAULT_IMAGE_CANVAS_VIEWPORT,
+  useImageCanvasViewportControls,
+} from './useImageCanvasViewportControls';
+
+export function ImageCanvasEditorView() {
+  const authUi = useAuthUi();
+  const editorRootRef = useRef<HTMLElement | null>(null);
+  const canvasViewportRef = useRef<HTMLDivElement | null>(null);
+  const assetListRef = useRef<HTMLDivElement | null>(null);
+  const assetPointerDragRef = useRef<AssetPointerDragState | null>(null);
+  const authUiRef = useRef(authUi);
+  const hasRequestedLoginRef = useRef(false);
+  const layerCounterRef = useRef(0);
+  const layersRef = useRef<CanvasLayer[]>([]);
+  const canvasGenerationDialogsRef = useRef<CanvasGenerationDialogState[]>([]);
+  const viewportRef = useRef<CanvasViewport>(DEFAULT_IMAGE_CANVAS_VIEWPORT);
+  const captureCanvasHistoryRef = useRef<() => void>(() => {});
+  const resetCanvasInteractionStateRef = useRef<() => void>(() => {});
+  const specToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const musicToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const publicationToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const characterSpecButtonRef = useRef<HTMLButtonElement | null>(null);
+  const characterReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const generationReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const publicationReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const iconSpecButtonRef = useRef<HTMLButtonElement | null>(null);
+  const selectedLayerIdRef = useRef<string | null>(null);
+  const selectedLayerIdsRef = useRef<string[]>([]);
+  const setQuickEditPanelRef = useRef<
+    Dispatch<SetStateAction<QuickEditPanelState | null>>
+  >(() => {});
+  const deleteLayerByIdRef = useRef<(targetLayerId: string | null) => void>(
+    () => {},
+  );
+  const suppressAssetClickRef = useRef(false);
+  const [layers, setLayers] = useState<CanvasLayer[]>([]);
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
+  const [selectedLayerIds, setSelectedLayerIds] = useState<string[]>([]);
+  const [hoveredLayerId, setHoveredLayerId] = useState<string | null>(null);
+  const [metadataLayer, setMetadataLayer] = useState<CanvasLayer | null>(null);
+  const [pendingGenerationDeleteDialog, setPendingGenerationDeleteDialog] =
+    useState<CanvasGenerationDialogState | null>(null);
+  const [imageContextMenu, setImageContextMenu] =
+    useState<ImageContextMenuState | null>(null);
+  const [contextMenu, setContextMenu] = useState<CanvasContextMenuState | null>(
+    null,
+  );
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+  const captureViewportHistory = useCallback(() => {
+    captureCanvasHistoryRef.current();
+  }, []);
+  const {
+    viewport,
+    setViewport,
+    canvasSize,
+    minimapModel,
+    updateScaleFromCenter,
+    fitLayers,
+    resolveCanvasPoint,
+    getCanvasDropPoint,
+    getCanvasPointFromClient,
+    moveViewportFromMinimapPointer,
+    updateViewportFromMinimapDrag,
+  } = useImageCanvasViewportControls({
+    canvasViewportRef,
+    layers,
+    captureCanvasHistory: captureViewportHistory,
+  });
+
+  selectedLayerIdRef.current = selectedLayerId;
+  selectedLayerIdsRef.current = selectedLayerIds;
+  layersRef.current = layers;
+  viewportRef.current = viewport;
+  authUiRef.current = authUi;
+  const openEditorLoginModal = useCallback(
+    (postLoginAction?: (() => void) | null) => {
+      authUiRef.current?.openLoginModal(postLoginAction);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (!authUi || authUi.user || authUi.canAccessProtectedData) {
+      hasRequestedLoginRef.current = false;
+      return;
+    }
+    if (hasRequestedLoginRef.current) {
+      return;
+    }
+    hasRequestedLoginRef.current = true;
+    authUi.openLoginModal(() => {
+      window.location.reload();
+    });
+  }, [authUi]);
+  const {
+    projectTitle,
+    setProjectTitle,
+    projectRenameValue,
+    setProjectRenameValue,
+    isRenamingProject,
+    isProjectRenameSaving,
+    projectRenameError,
+    activeSidebarPanel,
+    setActiveSidebarPanel,
+    activeTool,
+    setActiveTool,
+    isZoomMenuOpen,
+    isBackgroundSettingsOpen,
+    isMinimapOpen,
+    canvasBackgroundColor,
+    canvasBackgroundHexValue,
+    startProjectRename,
+    cancelProjectRename,
+    submitProjectRename,
+    resetProjectRenameError,
+    applyCanvasBackgroundColor,
+    handleCanvasBackgroundHexChange,
+    closeEditorChromePanels,
+    toggleSidebarPanel,
+    toggleZoomMenu,
+    closeZoomMenu,
+    toggleBackgroundSettings,
+    toggleMinimap,
+  } = useImageCanvasEditorChrome({ openEditorLoginModal });
+  const removeCanvasLayersLinkedToAssets = useImageCanvasAssetLayerCleanup({
+    layers,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+  });
+  const {
+    assetFolders,
+    setAssetFolders,
+    assets,
+    setAssets,
+    groupedAssets,
+    allSelectableAssetsSelected,
+    renamingAsset,
+    setRenamingAsset,
+    renamingFolder,
+    setRenamingFolder,
+    creatingFolder,
+    setCreatingFolder,
+    newFolderName,
+    setNewFolderName,
+    activeUploadFolderId,
+    setActiveUploadFolderId,
+    isAssetSelectionMode,
+    setIsAssetSelectionMode,
+    selectedAssetIds,
+    setSelectedAssetIds,
+    assetMarquee,
+    assetPointerDrag,
+    setAssetPointerDrag,
+    assetMoveDropFolderId,
+    pinnedAssetMoveFolderId,
+    resolveAssetFolderId,
+    updateAssetMoveDropFolder,
+    startRenamingAsset,
+    commitAssetRename,
+    toggleAssetFolder,
+    commitNewAssetFolder,
+    deleteUploadedAsset,
+    startRenamingFolder,
+    commitFolderRename,
+    deleteAssetFolder,
+    toggleAssetSelected,
+    toggleAllAssetsSelected,
+    deleteSelectedAssets,
+    moveAssetToFolder,
+    closeAssetSelectionMode,
+    handleAssetMarqueePointerDown,
+    handleAssetMarqueePointerMove,
+    handleAssetMarqueePointerUp,
+  } = useImageCanvasAssetLibrary({
+    assetListRef,
+    canAccessProtectedData: authUi ? authUi.canAccessProtectedData : true,
+    openEditorLoginModal,
+    onDeleteAssets: removeCanvasLayersLinkedToAssets,
+  });
+
+  const handleActivateCanvasGenerationDialog = useCallback(() => {
+    setSelectedLayerId(null);
+    setSelectedLayerIds([]);
+    setImageContextMenu(null);
+  }, []);
+  const {
+    generateDialog,
+    setGenerateDialog,
+    generateDialogRef,
+    setInactiveGenerateDialogs,
+    inactiveGenerateDialogsRef,
+    activeCanvasGenerationDialog,
+    canvasGenerationDialogs,
+    openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    removeCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById,
+    archiveActiveCanvasGenerationDialog,
+    activateCanvasGenerationDialog,
+    restoreCanvasGenerationDialogs,
+    removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder,
+  } = useCanvasGenerationDialogs({
+    onActivate: handleActivateCanvasGenerationDialog,
+  });
+  canvasGenerationDialogsRef.current = canvasGenerationDialogs;
+  const canvasHistoryRefs = useMemo(
+    () => ({
+      layersRef,
+      viewportRef,
+      generateDialogRef,
+      inactiveGenerateDialogsRef,
+      selectedLayerIdRef,
+      selectedLayerIdsRef,
+    }),
+    [generateDialogRef, inactiveGenerateDialogsRef],
+  );
+  const canvasHistorySetters = useMemo(
+    () => ({
+      setLayers,
+      setViewport,
+      setGenerateDialog,
+      setInactiveGenerateDialogs,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    }),
+    [
+      setGenerateDialog,
+      setInactiveGenerateDialogs,
+      setLayers,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+      setViewport,
+    ],
+  );
+  const canvasHistoryResetters = useMemo(
+    () => ({
+      setHoveredLayerId,
+      setMetadataLayer,
+      resetCanvasInteractionState: () =>
+        resetCanvasInteractionStateRef.current(),
+    }),
+    [],
+  );
+  const {
+    canUndo,
+    canRedo,
+    captureCanvasHistory,
+    undoCanvasChange,
+    redoCanvasChange,
+  } = useCanvasHistory({
+    refs: canvasHistoryRefs,
+    setters: canvasHistorySetters,
+    resetters: canvasHistoryResetters,
+  });
+  captureCanvasHistoryRef.current = captureCanvasHistory;
+  const selectSingleLayer = useCallback(
+    (layerId: string | null) => {
+      setSelectedLayerId(layerId);
+      setSelectedLayerIds(layerId ? [layerId] : []);
+      if (layerId) {
+        setGenerateDialog((currentDialog) =>
+          isCanvasGenerationComposerVisible(currentDialog)
+            ? {
+                ...currentDialog,
+                composerOpen: false,
+              }
+            : currentDialog,
+        );
+      }
+    },
+    [setGenerateDialog],
+  );
+  const persistGeneratedAsset = useCallback(
+    (layer: CanvasLayer) => {
+      if (authUiRef.current && !authUiRef.current.canAccessProtectedData) {
+        openEditorLoginModal();
+        return;
+      }
+      createEditorAsset({
+        folderId: activeUploadFolderId,
+        label: layer.title,
+        imageSrc: layer.src,
+        objectKey: layer.objectKey,
+        assetObjectId: layer.assetObjectId,
+        width: layer.originalWidth,
+        height: layer.originalHeight,
+        sourceType: 'generated',
+        prompt: layer.prompt,
+        actualPrompt: layer.actualPrompt,
+        model: layer.model,
+        provider: layer.provider,
+        taskId: layer.taskId,
+        durationSeconds: layer.durationSeconds,
+        assetKind: layer.assetKind,
+        generationInputs: layer.generationInputs,
+      })
+        .then((asset) => {
+          setAssets((currentAssets) => [
+            ...currentAssets.filter(
+              (currentAsset) => currentAsset.id !== asset.assetId,
+            ),
+            {
+              id: asset.assetId,
+              label: asset.label,
+              src: asset.imageSrc,
+              mediaType: layer.mediaType,
+              width: asset.width,
+              height: asset.height,
+              folderId: asset.folderId,
+              sourceKind: 'uploaded',
+              sourceType: asset.sourceType,
+              persisted: true,
+              prompt: asset.prompt ?? undefined,
+              actualPrompt: asset.actualPrompt ?? undefined,
+              model: asset.model ?? undefined,
+              provider: asset.provider ?? undefined,
+              taskId: asset.taskId ?? undefined,
+              objectKey: asset.objectKey ?? undefined,
+              assetObjectId: asset.assetObjectId ?? undefined,
+              durationSeconds: asset.durationSeconds ?? layer.durationSeconds,
+              assetKind: canvasAssetKindOrNull(asset.assetKind),
+              generationInputs: generationInputsOrNull(asset.generationInputs),
+            },
+          ]);
+          setAssetFolders((currentFolders) =>
+            currentFolders.map((folder) =>
+              folder.id === asset.folderId
+                ? {
+                    ...folder,
+                    collapsed: false,
+                  }
+                : folder,
+            ),
+          );
+          setLayers((currentLayers) =>
+            currentLayers.map((currentLayer) =>
+              currentLayer.id === layer.id
+                ? {
+                    ...currentLayer,
+                    sourceAssetId: asset.assetId,
+                    objectKey: asset.objectKey ?? currentLayer.objectKey,
+                    assetObjectId:
+                      asset.assetObjectId ?? currentLayer.assetObjectId,
+                  }
+                : currentLayer,
+            ),
+          );
+        })
+        .catch((error: unknown) => {
+          if (
+            error instanceof Error &&
+            'status' in error &&
+            (error.status === 401 || error.status === 403)
+          ) {
+            openEditorLoginModal();
+          }
+        });
+    },
+    [activeUploadFolderId, openEditorLoginModal, setAssetFolders, setAssets],
+  );
+  const upsertGeneratedAsset = useCallback(
+    (asset: EditorAssetSnapshot) => {
+      setAssets((currentAssets) => [
+        ...currentAssets.filter(
+          (currentAsset) => currentAsset.id !== asset.assetId,
+        ),
+        {
+          id: asset.assetId,
+          label: asset.label,
+          src: asset.imageSrc,
+          width: asset.width,
+          height: asset.height,
+          folderId: asset.folderId,
+          sourceKind: 'uploaded',
+          sourceType: asset.sourceType,
+          persisted: true,
+          prompt: asset.prompt ?? undefined,
+          actualPrompt: asset.actualPrompt ?? undefined,
+          model: asset.model ?? undefined,
+          provider: asset.provider ?? undefined,
+          taskId: asset.taskId ?? undefined,
+          objectKey: asset.objectKey ?? undefined,
+          assetObjectId: asset.assetObjectId ?? undefined,
+          durationSeconds: asset.durationSeconds ?? undefined,
+          assetKind: canvasAssetKindOrNull(asset.assetKind),
+          generationInputs: generationInputsOrNull(asset.generationInputs),
+        },
+      ]);
+      setAssetFolders((currentFolders) =>
+        currentFolders.some((folder) => folder.id === asset.folderId)
+          ? currentFolders.map((folder) =>
+              folder.id === asset.folderId
+                ? { ...folder, collapsed: false }
+                : folder,
+            )
+          : [
+              ...currentFolders,
+              {
+                id: asset.folderId,
+                label: '项目素材',
+                collapsed: false,
+                systemDefault: true,
+                persisted: true,
+              },
+            ],
+      );
+    },
+    [setAssetFolders, setAssets],
+  );
+  const projectPersistenceRefs = useMemo(
+    () => ({
+      layersRef,
+      viewportRef,
+      canvasGenerationDialogsRef,
+    }),
+    [],
+  );
+  const projectPersistenceSetters = useMemo(
+    () => ({
+      setProjectTitle,
+      setProjectRenameValue,
+      setViewport,
+      setLayers,
+      selectSingleLayer,
+      setLayerCounter: (value: number) => {
+        layerCounterRef.current = value;
+      },
+      restoreCanvasGenerationDialogs,
+    }),
+    [
+      restoreCanvasGenerationDialogs,
+      selectSingleLayer,
+      setLayers,
+      setProjectRenameValue,
+      setProjectTitle,
+      setViewport,
+    ],
+  );
+  const { projectId, appendCanvasLayersWithResources, applyProjectSnapshot } =
+    useImageCanvasProjectPersistence({
+      refs: projectPersistenceRefs,
+      setters: projectPersistenceSetters,
+      layers,
+      canvasGenerationDialogs,
+      viewport,
+      canAccessProtectedData: authUi ? authUi.canAccessProtectedData : true,
+      openEditorLoginModal,
+    });
+  const persistUpdatedLayerResource = useCallback(
+    (layer: CanvasLayer) => {
+      if (!projectId) {
+        return;
+      }
+      void createEditorProjectResource(projectId, {
+        imageSrc: layer.src,
+        width: layer.originalWidth,
+        height: layer.originalHeight,
+        sourceType: layer.sourceType,
+        prompt: layer.prompt,
+        actualPrompt: layer.actualPrompt,
+        model: layer.model,
+        provider: layer.provider,
+        taskId: layer.taskId,
+        durationSeconds: layer.durationSeconds,
+        sourceResourceId: layer.sourceResourceId,
+        assetKind: layer.assetKind,
+        generationInputs: layer.generationInputs,
+      }).then((resource) => {
+        setLayers((currentLayers) => {
+          const nextLayers = currentLayers.map((currentLayer) =>
+            currentLayer.id === layer.id
+              ? {
+                  ...currentLayer,
+                  resourceId: resource.resourceId,
+                }
+              : currentLayer,
+          );
+          layersRef.current = nextLayers;
+          return nextLayers;
+        });
+      });
+    },
+    [projectId],
+  );
+  const {
+    assetExportStatus,
+    isExportingAssets,
+    exportCanvasAssets,
+    exportLayerImage,
+  } = useImageCanvasAssetExportWorkflow({
+    layers,
+    projectId,
+    projectTitle,
+  });
+  const {
+    uploadInputRef,
+    uploadTarget,
+    requestUpload,
+    handleUploadInputChange,
+    addUploadedFiles,
+  } = useImageCanvasUploadWorkflow({
+    canAccessProtectedData: authUi ? authUi.canAccessProtectedData : true,
+    openEditorLoginModal,
+    projectId,
+    assetFolders,
+    activeUploadFolderId,
+    canvasSize,
+    viewport,
+    activeTool,
+    allocateUploadIndex: () => {
+      layerCounterRef.current += 1;
+      return layerCounterRef.current;
+    },
+    setAssetFolders,
+    setAssets,
+    setLayers,
+    setGenerateDialog,
+    setQuickEditPanel: (updater) => setQuickEditPanelRef.current(updater),
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+  });
+  const generationSurface = useImageCanvasGenerationSurface({
+    layers,
+    canvasSize,
+    viewport,
+    setViewport,
+    setLayers,
+    layerCounterRef,
+    specToolWrapRef,
+    musicToolWrapRef,
+    publicationToolWrapRef,
+    characterSpecButtonRef,
+    characterReferenceButtonRef,
+    generationReferenceButtonRef,
+    publicationReferenceButtonRef,
+    iconSpecButtonRef,
+    generateDialog,
+    setGenerateDialog,
+    activeCanvasGenerationDialog,
+    canvasGenerationDialogs,
+    openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById,
+    archiveActiveCanvasGenerationDialog,
+    removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    fitLayers,
+    captureCanvasHistory,
+    setActiveTool,
+    setActiveSidebarPanel,
+    setMetadataLayer,
+    setImageContextMenu,
+    requestUpload,
+    persistGeneratedAsset,
+    persistUpdatedLayerResource,
+    projectId,
+    assetFolderId: activeUploadFolderId,
+    upsertGeneratedAsset,
+    applyProjectSnapshot,
+  });
+  const {
+    setQuickEditPanel,
+    setCropExpandPanel,
+    setCharacterAnimationPanel,
+    setIsSpecMenuOpen,
+    setIsGenerationReferenceMenuOpen,
+    setIsCharacterSpecMenuOpen,
+    setIsCharacterReferenceMenuOpen,
+    isPickingGenerationReferenceFromCanvas,
+    setIsPickingGenerationReferenceFromCanvas,
+    isPickingQuickEditReferenceFromCanvas,
+    setIsPickingQuickEditReferenceFromCanvas,
+    isPickingPublicationReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+    isPickingCharacterSpecFromCanvas,
+    setIsPickingCharacterSpecFromCanvas,
+    isPickingCharacterReferenceFromCanvas,
+    setIsPickingCharacterReferenceFromCanvas,
+    setIsIconSpecMenuOpen,
+    isPickingIconSpecFromCanvas,
+    setIsPickingIconSpecFromCanvas,
+    setIsUiDesignSpecMenuOpen,
+    isPickingUiDesignSpecFromCanvas,
+    setIsPickingUiDesignSpecFromCanvas,
+    openCharacterAnimationPanel,
+    openQuickEditPanel,
+    openRedrawPanel,
+    openCropExpandPanel,
+    removeSelectedLayerBackground,
+    extractUiDesignAssets,
+    pickCharacterSpecFromLayer,
+    pickGenerationReferenceFromLayer,
+    pickQuickEditReferenceFromLayer,
+    pickPublicationReferenceFromLayer,
+    pickCharacterReferenceFromLayer,
+    pickIconSpecFromLayer,
+    pickUiDesignSpecFromLayer,
+    hideGeneratedLayerPanelAfterBlur,
+    clearDeletedLayerGenerationState,
+    generationComposerStyle,
+    generationComposerNode,
+    switchGenerationTool,
+  } = generationSurface;
+  setQuickEditPanelRef.current = setQuickEditPanel;
+  const clearGenerationPanelsAfterBlur = useCallback(() => {
+    setQuickEditPanel(null);
+    setCropExpandPanel(null);
+    setCharacterAnimationPanel(null);
+  }, [setCharacterAnimationPanel, setCropExpandPanel, setQuickEditPanel]);
+  const {
+    selectedLayer,
+    selectedToolbarStyle,
+    imageContextMenuLayer,
+    contextShouldShowLayer,
+    contextShouldUnlockLayer,
+    clearCanvasFocus,
+    handleCanvasContextMenu,
+    handleLayerContextMenu,
+  } = useImageCanvasStageController({
+    layers,
+    canvasGenerationDialogs,
+    selectedLayerId,
+    selectedLayerIds,
+    imageContextMenu,
+    setImageContextMenu,
+    contextMenu,
+    setContextMenu,
+    viewport,
+    canvasSize,
+    selectSingleLayer,
+    hideGeneratedLayerPanelAfterBlur,
+    clearGenerationPanelsAfterBlur,
+    getCanvasPointFromClient,
+  });
+  const {
+    canvasClipboard,
+    pasteCanvasClipboard,
+    copyContextLayers,
+    duplicateContextLayers,
+    moveContextLayers,
+    groupContextLayers,
+    ungroupContextLayers,
+    toggleContextLayerVisibility,
+    toggleContextLayerLock,
+    flipContextLayers,
+    deleteContextLayers,
+    exportContextLayer,
+    deleteLayerById,
+    deleteSelectedLayer,
+    groupSelectedLayers,
+  } = useImageCanvasLayerCommands({
+    layers,
+    contextMenu,
+    selectedLayerId,
+    selectedLayerIds,
+    canvasGenerationDialogs,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+    setHoveredLayerId,
+    setMetadataLayer,
+    setContextMenu,
+    setImageContextMenu,
+    setActiveTool,
+    captureCanvasHistory,
+    selectSingleLayer,
+    onDeleteLayerSideEffects: clearDeletedLayerGenerationState,
+    onDeleteGenerationDialogSideEffects: removeCanvasGenerationDialogById,
+    exportLayerImage,
+  });
+  const {
+    canvasMarquee,
+    isPanning,
+    snapGuide,
+    effectiveTool,
+    setIsSpacePanning,
+    setShiftPressed,
+    clearActiveInteraction,
+    handleCanvasPointerDown,
+    handleLayerPointerDown,
+    handleLayerClick,
+    handleGenerationFramePointerDown,
+    handleMinimapPointerDown,
+    handlePointerMove,
+    finishDrag,
+  } = useImageCanvasStageInteractions({
+    canvasViewportRef,
+    activeTool,
+    layers,
+    setLayers,
+    viewport,
+    setViewport,
+    selectedLayerIds,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+    generateDialog,
+    canvasGenerationDialogs,
+    setGenerateDialog,
+    isPickingCharacterSpecFromCanvas,
+    isPickingGenerationReferenceFromCanvas,
+    isPickingQuickEditReferenceFromCanvas,
+    isPickingPublicationReferenceFromCanvas,
+    isPickingCharacterReferenceFromCanvas,
+    isPickingIconSpecFromCanvas,
+    isPickingUiDesignSpecFromCanvas,
+    clearCanvasFocus,
+    pickCharacterSpecFromLayer,
+    pickGenerationReferenceFromLayer,
+    pickQuickEditReferenceFromLayer,
+    pickPublicationReferenceFromLayer,
+    pickCharacterReferenceFromLayer,
+    pickIconSpecFromLayer,
+    pickUiDesignSpecFromLayer,
+    activateCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    moveViewportFromMinimapPointer,
+    updateViewportFromMinimapDrag,
+    minimapScale: minimapModel?.scale ?? 1,
+    onCloseImageContextMenu: () => setImageContextMenu(null),
+  });
+  resetCanvasInteractionStateRef.current = clearActiveInteraction;
+  const deleteLayerByIdFromShortcut = useCallback(
+    (layerId: string | null) => deleteLayerByIdRef.current(layerId),
+    [],
+  );
+  const removeCanvasGenerationDialog = useCallback(
+    (dialogId: string) => {
+      captureCanvasHistory();
+      removeCanvasGenerationDialogById(dialogId);
+      setSelectedLayerId(null);
+      setSelectedLayerIds([]);
+      setImageContextMenu(null);
+      setContextMenu(null);
+      setActiveTool('select');
+    },
+    [
+      captureCanvasHistory,
+      removeCanvasGenerationDialogById,
+      setActiveTool,
+      setContextMenu,
+      setImageContextMenu,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    ],
+  );
+  const requestRemoveCanvasGenerationDialog = useCallback(
+    (dialog: CanvasGenerationDialogState) => {
+      if (dialog.status === 'generating') {
+        activateCanvasGenerationDialog(dialog);
+        setPendingGenerationDeleteDialog(dialog);
+        return;
+      }
+      removeCanvasGenerationDialog(dialog.id);
+    },
+    [activateCanvasGenerationDialog, removeCanvasGenerationDialog],
+  );
+  const confirmRemoveGeneratingDialog = useCallback(() => {
+    const dialog = pendingGenerationDeleteDialog;
+    if (!dialog) {
+      return;
+    }
+    setPendingGenerationDeleteDialog(null);
+    removeCanvasGenerationDialog(dialog.id);
+  }, [pendingGenerationDeleteDialog, removeCanvasGenerationDialog]);
+  const updateLayerAssetKind = useCallback(
+    (layerId: string, assetKind: CanvasAssetKind | null) => {
+      const targetLayer = layersRef.current.find((layer) => layer.id === layerId);
+      if (!targetLayer || targetLayer.assetKind === assetKind) {
+        return;
+      }
+      captureCanvasHistory();
+      const nextLayer = {
+        ...targetLayer,
+        assetKind,
+      };
+      setLayers((currentLayers) => {
+        const nextLayers = currentLayers.map((layer) =>
+          layer.id === layerId ? { ...layer, assetKind } : layer,
+        );
+        layersRef.current = nextLayers;
+        return nextLayers;
+      });
+      setMetadataLayer((currentLayer) =>
+        currentLayer?.id === layerId ? nextLayer : currentLayer,
+      );
+      persistUpdatedLayerResource(nextLayer);
+      setImageContextMenu(null);
+      setContextMenu(null);
+    },
+    [captureCanvasHistory, persistUpdatedLayerResource],
+  );
+
+  useImageCanvasKeyboardShortcuts({
+    generateDialogRef,
+    selectedLayerIdRef,
+    selectedLayerIdsRef,
+    redoCanvasChange,
+    undoCanvasChange,
+    deleteLayerById: deleteLayerByIdFromShortcut,
+    deleteSelectedCanvasObjects: deleteSelectedLayer,
+    requestRemoveCanvasGenerationDialog,
+    setActiveTool,
+    setGenerateDialog,
+    setImageContextMenu,
+    setContextMenu,
+    setQuickEditPanel,
+    closeEditorChromePanels,
+    setIsSpecMenuOpen,
+    setIsGenerationReferenceMenuOpen,
+    setIsPublicationReferenceMenuOpen:
+      generationSurface.setIsPublicationReferenceMenuOpen,
+    setIsPickingGenerationReferenceFromCanvas,
+    setIsPickingQuickEditReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+    setIsCharacterSpecMenuOpen,
+    setIsCharacterReferenceMenuOpen,
+    setIsPickingCharacterSpecFromCanvas,
+    setIsPickingCharacterReferenceFromCanvas,
+    setIsIconSpecMenuOpen,
+    setIsPickingIconSpecFromCanvas,
+    setIsUiDesignSpecMenuOpen,
+    setIsPickingUiDesignSpecFromCanvas,
+    setIsSpacePanning,
+    setShiftPressed,
+  });
+
+  useEffect(() => {
+    const blockBrowserZoom = (event: WheelEvent) => {
+      const editorElement = editorRootRef.current;
+      if (
+        editorElement &&
+        event.target instanceof Node &&
+        editorElement.contains(event.target) &&
+        (event.ctrlKey || event.metaKey)
+      ) {
+        event.preventDefault();
+      }
+    };
+    window.addEventListener('wheel', blockBrowserZoom, {
+      capture: true,
+      passive: false,
+    });
+    return () => {
+      window.removeEventListener('wheel', blockBrowserZoom, { capture: true });
+    };
+  }, []);
+
+  const {
+    addAssetLayer,
+    handleCanvasDragOver,
+    handleCanvasDragLeave,
+    handleCanvasDrop,
+  } = useImageCanvasAssetCanvasBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    assetFolders,
+    layerCounterRef,
+    viewport,
+    canvasSize,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    getCanvasDropPoint,
+    setAssetPointerDrag,
+    setActiveUploadFolderId,
+    setUploadDropTarget,
+    setHoveredLayerId,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    captureCanvasHistory,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    addUploadedFiles,
+  });
+
+  deleteLayerByIdRef.current = deleteLayerById;
+
+  const switchTool = (tool: CanvasTool) => {
+    clearActiveInteraction();
+    if (tool === 'upload') {
+      requestUpload('asset', { addToCanvas: true });
+      return;
+    }
+    if (switchGenerationTool(tool)) {
+      return;
+    }
+    setActiveTool(tool);
+  };
+  const assetDragPreview = assetPointerDrag?.active
+    ? {
+        x: assetPointerDrag.currentClientX,
+        y: assetPointerDrag.currentClientY,
+        label:
+          assets.find((asset) => asset.id === assetPointerDrag.assetId)
+            ?.label ?? '素材',
+      }
+    : null;
+  const sidebarProps = {
+    activeSidebarPanel,
+    assetListRef,
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    groupedAssets,
+    assetFolders,
+    layers,
+    selectedLayerId,
+    selectedLayerIds,
+    isAssetSelectionMode,
+    selectedAssetIds,
+    assetMoveDropFolderId,
+    pinnedAssetMoveFolderId,
+    creatingFolder,
+    newFolderName,
+    renamingFolder,
+    renamingAsset,
+    allSelectableAssetsSelected,
+    assetMarquee,
+    setIsAssetSelectionMode,
+    setCreatingFolder,
+    setNewFolderName,
+    setRenamingFolder,
+    setRenamingAsset,
+    setActiveUploadFolderId,
+    setUploadDropTarget,
+    setAssetPointerDrag,
+    setSelectedAssetIds,
+    setImageContextMenu,
+    setContextMenu,
+    onAssetMarqueePointerDown: handleAssetMarqueePointerDown,
+    onAssetMarqueePointerMove: handleAssetMarqueePointerMove,
+    onAssetMarqueePointerUp: handleAssetMarqueePointerUp,
+    updateAssetMoveDropFolder,
+    addUploadedFiles,
+    requestUpload,
+    moveAssetToFolder,
+    commitNewAssetFolder,
+    toggleAssetFolder,
+    startRenamingFolder,
+    commitFolderRename,
+    deleteAssetFolder,
+    startRenamingAsset,
+    commitAssetRename,
+    deleteUploadedAsset,
+    toggleAssetSelected,
+    addAssetLayer,
+    toggleAllAssetsSelected,
+    deleteSelectedAssets,
+    closeAssetSelectionMode,
+    groupSelectedLayers,
+    selectSingleLayer,
+    resolveContextMenuPosition,
+    getCanvasPointFromClient,
+  };
+  const topbarProps = {
+    projectId,
+    projectTitle,
+    projectRenameValue,
+    isRenamingProject,
+    isProjectRenameSaving,
+    projectRenameError,
+    layers,
+    assetExportStatus,
+    isExportingAssets,
+    setProjectRenameValue,
+    startProjectRename,
+    cancelProjectRename,
+    submitProjectRename,
+    resetProjectRenameError,
+    exportCanvasAssets,
+  };
+  const stageProps = {
+    canvasViewportRef,
+    specToolWrapRef,
+    musicToolWrapRef,
+    publicationToolWrapRef,
+    isPanning,
+    effectiveTool,
+    canvasBackgroundColor,
+    canvasBackgroundHexValue,
+    viewport,
+    snapGuide,
+    layers,
+    selectedLayer,
+    selectedLayerIds,
+    hoveredLayerId,
+    canvasMarquee,
+    canvasGenerationDialogs,
+    generateDialog,
+    cropExpandPanel: generationSurface.cropExpandPanel,
+    cropExpandSourceLayer: generationSurface.cropExpandSourceLayer,
+    generationComposerStyle,
+    selectedToolbarStyle,
+    uploadDropTarget,
+    contextMenu,
+    canvasClipboard,
+    imageContextMenu,
+    imageContextMenuLayer,
+    contextShouldShowLayer,
+    contextShouldUnlockLayer,
+    canUndo,
+    canRedo,
+    isZoomMenuOpen,
+    isBackgroundSettingsOpen,
+    activeSidebarPanel,
+    isMinimapOpen,
+    minimapModel,
+    onCanvasPointerDown: handleCanvasPointerDown,
+    onCanvasPointerMove: handlePointerMove,
+    onCanvasPointerUp: finishDrag,
+    onCanvasDragOver: handleCanvasDragOver,
+    onCanvasDragLeave: handleCanvasDragLeave,
+    onCanvasDrop: handleCanvasDrop,
+    onCanvasContextMenu: handleCanvasContextMenu,
+    onLayerPointerDown: handleLayerPointerDown,
+    onLayerClick: handleLayerClick,
+    onSelectLayer: selectSingleLayer,
+    onLayerContextMenu: handleLayerContextMenu,
+    onLayerMouseEnter: setHoveredLayerId,
+    onLayerMouseLeave: (layerId: string) =>
+      setHoveredLayerId((currentId) =>
+        currentId === layerId ? null : currentId,
+      ),
+    onOpenLayerMetadata: (layer: CanvasLayer) => {
+      setMetadataLayer(layer);
+      selectSingleLayer(layer.id);
+    },
+    onUpdateLayerAssetKind: updateLayerAssetKind,
+    onGenerationFramePointerDown: handleGenerationFramePointerDown,
+    onActivateGenerationDialog: activateCanvasGenerationDialog,
+    onCropExpandHandlePointerDown:
+      generationSurface.startCropExpandFrameResize,
+    onOpenQuickEditPanel: openQuickEditPanel,
+    onOpenRedrawPanel: openRedrawPanel,
+    onOpenCropExpandPanel: openCropExpandPanel,
+    onRemoveBackground: removeSelectedLayerBackground,
+    onExtractUiDesignAssets: extractUiDesignAssets,
+    onOpenCharacterAnimationPanel: openCharacterAnimationPanel,
+    onDownloadLayer: exportLayerImage,
+    onPasteCanvasClipboard: pasteCanvasClipboard,
+    onCopyContextLayers: copyContextLayers,
+    onDuplicateContextLayers: duplicateContextLayers,
+    onMoveContextLayers: moveContextLayers,
+    onGroupContextLayers: groupContextLayers,
+    onUngroupContextLayers: ungroupContextLayers,
+    onToggleContextLayerVisibility: toggleContextLayerVisibility,
+    onToggleContextLayerLock: toggleContextLayerLock,
+    onFlipContextLayers: flipContextLayers,
+    onExportContextLayer: exportContextLayer,
+    onDeleteContextLayers: deleteContextLayers,
+    onDeleteLayerById: deleteLayerById,
+    onCloseContextMenu: () => setContextMenu(null),
+    onCloseImageContextMenu: () => setImageContextMenu(null),
+    onUpdateScaleFromCenter: updateScaleFromCenter,
+    onFitLayers: fitLayers,
+    onUndoCanvasChange: undoCanvasChange,
+    onRedoCanvasChange: redoCanvasChange,
+    onToggleZoomMenu: toggleZoomMenu,
+    onCloseZoomMenu: closeZoomMenu,
+    onToggleBackgroundSettings: toggleBackgroundSettings,
+    onApplyCanvasBackgroundColor: applyCanvasBackgroundColor,
+    onCanvasBackgroundHexChange: handleCanvasBackgroundHexChange,
+    onToggleSidebarPanel: toggleSidebarPanel,
+    onToggleMinimap: toggleMinimap,
+    onMinimapPointerDown: handleMinimapPointerDown,
+    onSwitchTool: switchTool,
+    onOpenToolOptions: generationSurface.openToolbarOptionMenu,
+    onCloseToolOptions: generationSurface.closeToolbarOptionMenu,
+    children: generationComposerNode,
+  };
+
+  return (
+    <>
+      <ImageCanvasEditorShellView
+        editorRootRef={editorRootRef}
+        uploadInputRef={uploadInputRef}
+        uploadAccept={getEditorUploadAccept(uploadTarget)}
+        onUploadInputChange={handleUploadInputChange}
+        assetDragPreview={assetDragPreview}
+        sidebarProps={sidebarProps}
+        topbarProps={topbarProps}
+        stageProps={stageProps}
+        metadataProps={{
+          layer: metadataLayer,
+          onClose: () => setMetadataLayer(null),
+        }}
+      />
+      <PlatformDangerConfirmDialog
+        open={Boolean(pendingGenerationDeleteDialog)}
+        title="删除生成中的占位图"
+        confirmLabel="确认删除"
+        onClose={() => setPendingGenerationDeleteDialog(null)}
+        onConfirm={confirmRemoveGeneratingDialog}
+      >
+        删除后会停止在画布中显示这个生成任务，已消耗的泥点不会返还。
+      </PlatformDangerConfirmDialog>
+    </>
+  );
+}
+
+export default ImageCanvasEditorView;
diff --git a/src/components/image-editor/ImageCanvasExportModel.test.ts b/src/components/image-editor/ImageCanvasExportModel.test.ts
new file mode 100644
index 000000000..31162993b
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasExportModel.test.ts
@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  buildLayerExportMetadata,
+  dataUrlToBlob,
+  formatExportDate,
+  getImageExtensionFromTypeOrSrc,
+  getLayerAssetExtensionFromTypeOrSrc,
+  getLayerExportKey,
+  readLayerAssetBlob,
+  sanitizeExportFilePart,
+} from './ImageCanvasExportModel';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+
+describe('ImageCanvasExportModel', () => {
+  it('normalizes export file names and dates', () => {
+    expect(sanitizeExportFilePart('  角色/草图:*?  ', 'fallback')).toBe(
+      '角色 草图',
+    );
+    expect(sanitizeExportFilePart('   ', 'fallback')).toBe('fallback');
+    expect(formatExportDate(new Date('2026-06-17T01:02:03.000Z'))).toBe(
+      '20260617',
+    );
+  });
+
+  it('chooses stable image export keys by persistence identity', () => {
+    expect(
+      getLayerExportKey({
+        ...buildLayer(),
+        assetObjectId: 'object-1',
+        objectKey: 'object-key',
+        sourceAssetId: 'asset-1',
+        src: 'data:image/png;base64,one',
+      }),
+    ).toBe('object-1');
+    expect(
+      getLayerExportKey({
+        ...buildLayer(),
+        objectKey: 'object-key',
+        sourceAssetId: 'asset-1',
+        src: 'data:image/png;base64,one',
+      }),
+    ).toBe('object-key');
+  });
+
+  it('detects image extensions from content type before falling back to src', () => {
+    expect(getImageExtensionFromTypeOrSrc('image/jpeg', '/image.png')).toBe(
+      'jpg',
+    );
+    expect(getImageExtensionFromTypeOrSrc('', '/image.webp?x=1')).toBe('webp');
+    expect(getImageExtensionFromTypeOrSrc('', '/image.unknown')).toBe('png');
+    expect(
+      getLayerAssetExtensionFromTypeOrSrc(
+        'video',
+        'video/mp4',
+        '/video.png',
+      ),
+    ).toBe('mp4');
+    expect(
+      getLayerAssetExtensionFromTypeOrSrc(
+        'video',
+        '',
+        '/generated-character-drafts/editor/preview.mp4',
+      ),
+    ).toBe('mp4');
+    expect(
+      getLayerAssetExtensionFromTypeOrSrc(
+        'audio',
+        '',
+        '/generated-audios/effect.wav?token=1',
+      ),
+    ).toBe('wav');
+  });
+
+  it('converts data URLs and builds layer metadata for manifest files', async () => {
+    const blob = dataUrlToBlob('data:text/plain;base64,SGVsbG8=');
+    expect(blob.type).toBe('text/plain');
+    expect(await blob.text()).toBe('Hello');
+
+    expect(buildLayerExportMetadata(buildLayer(), 'images/001-layer.png')).toEqual({
+      layerId: 'layer-1',
+      title: '导出图层',
+      file: 'images/001-layer.png',
+      mediaType: 'image',
+      sourceType: 'generated',
+      prompt: '生成提示',
+      actualPrompt: '实际提示',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'task-1',
+      objectKey: 'generated/layer.png',
+      assetObjectId: undefined,
+      sourceResourceId: 'source-resource',
+      sourceAssetId: 'asset-1',
+      exportError: undefined,
+      canvas: {
+        x: 10,
+        y: 20,
+        width: 512,
+        height: 512,
+        originalWidth: 1024,
+        originalHeight: 1024,
+        zIndex: 3,
+        groupId: 'group-1',
+        hidden: true,
+        locked: false,
+        flipX: true,
+        flipY: false,
+      },
+    });
+  });
+
+  it('reads private object-key assets through signed URLs before exporting', async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async (url: string) => {
+      if (url.startsWith('/api/assets/read-url?')) {
+        return new Response(
+          JSON.stringify({
+            ok: true,
+            data: {
+              read: {
+                objectKey: 'generated/video.mp4',
+                signedUrl: 'https://oss.example.com/generated/video.mp4?x-oss-signature=1',
+                expiresAt: '2026-06-20T00:00:00.000Z',
+              },
+            },
+            error: null,
+            meta: { apiVersion: '2026-06-16' },
+          }),
+        );
+      }
+      if (url === 'https://oss.example.com/generated/video.mp4?x-oss-signature=1') {
+        return new Response(new Blob(['video'], { type: 'video/mp4' }));
+      }
+      return new Response(null, { status: 404 });
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    try {
+      const blob = await readLayerAssetBlob(
+        buildLayer({
+          src: '/generated-editor-videos/video.mp4',
+          mediaType: 'video',
+          objectKey: 'generated/video.mp4',
+        }),
+      );
+
+      expect(blob.type).toBe('video/mp4');
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.stringContaining('/api/assets/read-url?objectKey=generated%2Fvideo.mp4'),
+        expect.any(Object),
+      );
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://oss.example.com/generated/video.mp4?x-oss-signature=1',
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+function buildLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '导出图层',
+    src: 'data:image/png;base64,one',
+    x: 10,
+    y: 20,
+    width: 512,
+    height: 512,
+    originalWidth: 1024,
+    originalHeight: 1024,
+    zIndex: 3,
+    sourceType: 'generated',
+    prompt: '生成提示',
+    actualPrompt: '实际提示',
+    model: 'gpt-image-2',
+    provider: 'VectorEngine',
+    taskId: 'task-1',
+    objectKey: 'generated/layer.png',
+    sourceResourceId: 'source-resource',
+    sourceAssetId: 'asset-1',
+    groupId: 'group-1',
+    hidden: true,
+    locked: false,
+    flipX: true,
+    flipY: false,
+    ...overrides,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasExportModel.ts b/src/components/image-editor/ImageCanvasExportModel.ts
new file mode 100644
index 000000000..3e5de65b1
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasExportModel.ts
@@ -0,0 +1,207 @@
+import type {
+  CanvasAssetExportMetadata,
+  CanvasMediaType,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  getSignedAssetReadUrl,
+  resolveAssetReadUrl,
+} from '../../services/assetReadUrlService';
+
+export function sanitizeExportFilePart(value: string, fallback: string) {
+  const safeValue = value
+    .trim()
+    .replace(/[\\/:*?"<>|]+/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim();
+  return safeValue || fallback;
+}
+
+export function formatExportDate(date: Date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}${month}${day}`;
+}
+
+export function getLayerExportKey(layer: CanvasLayer) {
+  return (
+    layer.assetObjectId ||
+    layer.objectKey ||
+    layer.sourceAssetId ||
+    layer.sourceResourceId ||
+    layer.src
+  );
+}
+
+export function getImageExtensionFromTypeOrSrc(type: string, src: string) {
+  return getLayerAssetExtensionFromTypeOrSrc('image', type, src);
+}
+
+function getExtensionFromSrc(src: string) {
+  const withoutQuery = src.split(/[?#]/u)[0] ?? '';
+  const match = /\.([a-z0-9]+)$/iu.exec(withoutQuery);
+  return match?.[1]?.toLowerCase() ?? null;
+}
+
+function pickKnownExtension(
+  extension: string | null,
+  allowedExtensions: string[],
+  fallback: string,
+) {
+  return extension && allowedExtensions.includes(extension) ? extension : fallback;
+}
+
+export function getLayerAssetExtensionFromTypeOrSrc(
+  mediaType: CanvasMediaType | undefined,
+  type: string,
+  src: string,
+) {
+  const normalizedType = type.toLowerCase();
+  const extensionFromSrc = getExtensionFromSrc(src);
+  if (mediaType === 'audio') {
+    if (normalizedType.includes('mpeg') || normalizedType.includes('mp3')) {
+      return 'mp3';
+    }
+    if (normalizedType.includes('wav')) {
+      return 'wav';
+    }
+    if (normalizedType.includes('ogg')) {
+      return 'ogg';
+    }
+    if (normalizedType.includes('aac')) {
+      return 'aac';
+    }
+    if (normalizedType.includes('flac')) {
+      return 'flac';
+    }
+    return pickKnownExtension(
+      extensionFromSrc,
+      ['mp3', 'wav', 'ogg', 'aac', 'flac', 'm4a'],
+      'mp3',
+    );
+  }
+  if (mediaType === 'video') {
+    if (normalizedType.includes('mp4')) {
+      return 'mp4';
+    }
+    if (normalizedType.includes('webm')) {
+      return 'webm';
+    }
+    if (normalizedType.includes('quicktime')) {
+      return 'mov';
+    }
+    return pickKnownExtension(extensionFromSrc, ['mp4', 'webm', 'mov'], 'mp4');
+  }
+  if (
+    normalizedType.includes('jpeg') ||
+    extensionFromSrc === 'jpg' ||
+    extensionFromSrc === 'jpeg'
+  ) {
+    return 'jpg';
+  }
+  if (normalizedType.includes('webp') || extensionFromSrc === 'webp') {
+    return 'webp';
+  }
+  if (normalizedType.includes('gif') || extensionFromSrc === 'gif') {
+    return 'gif';
+  }
+  if (normalizedType.includes('svg') || extensionFromSrc === 'svg') {
+    return 'svg';
+  }
+  return 'png';
+}
+
+export function dataUrlToBlob(dataUrl: string) {
+  const [header = '', payload = ''] = dataUrl.split(',');
+  const mimeMatch = /^data:([^;]+)(;base64)?$/iu.exec(header);
+  const type = mimeMatch?.[1] ?? 'application/octet-stream';
+  const isBase64 = Boolean(mimeMatch?.[2]);
+  const binary = isBase64
+    ? typeof atob === 'function'
+      ? atob(payload)
+      : Buffer.from(payload, 'base64').toString('binary')
+    : decodeURIComponent(payload);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return new Blob([bytes], { type });
+}
+
+export async function readLayerAssetBlob(layer: CanvasLayer) {
+  if (layer.src.startsWith('data:')) {
+    return dataUrlToBlob(layer.src);
+  }
+  const source = layer.objectKey
+    ? await getSignedAssetReadUrl(
+        { objectKey: layer.objectKey },
+        undefined,
+        { cacheVersion: layer.taskId ?? layer.resourceId },
+      )
+    : await resolveAssetReadUrl(layer.src);
+  const response = await fetch(source);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return response.blob();
+}
+
+export const readLayerImageBlob = readLayerAssetBlob;
+
+export async function blobToUint8Array(blob: Blob) {
+  if (typeof blob.arrayBuffer === 'function') {
+    return new Uint8Array(await blob.arrayBuffer());
+  }
+  return new Promise<Uint8Array>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const result = reader.result;
+      if (result instanceof ArrayBuffer) {
+        resolve(new Uint8Array(result));
+        return;
+      }
+      reject(new Error('Blob 读取失败'));
+    };
+    reader.onerror = () => reject(new Error('Blob 读取失败'));
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+export function buildLayerExportMetadata(
+  layer: CanvasLayer,
+  file: string | null,
+  exportError?: string,
+): CanvasAssetExportMetadata['layers'][number] {
+  return {
+    layerId: layer.id,
+    title: layer.title,
+    file,
+    mediaType: layer.mediaType ?? 'image',
+    sourceType: layer.sourceType,
+    prompt: layer.prompt,
+    actualPrompt: layer.actualPrompt,
+    model: layer.model,
+    provider: layer.provider,
+    taskId: layer.taskId,
+    objectKey: layer.objectKey,
+    assetObjectId: layer.assetObjectId,
+    sourceResourceId: layer.sourceResourceId,
+    sourceAssetId: layer.sourceAssetId,
+    exportError,
+    canvas: {
+      x: layer.x,
+      y: layer.y,
+      width: layer.width,
+      height: layer.height,
+      originalWidth: layer.originalWidth,
+      originalHeight: layer.originalHeight,
+      zIndex: layer.zIndex,
+      groupId: layer.groupId,
+      hidden: layer.hidden,
+      locked: layer.locked,
+      flipX: layer.flipX,
+      flipY: layer.flipY,
+    },
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasFileModel.test.ts b/src/components/image-editor/ImageCanvasFileModel.test.ts
new file mode 100644
index 000000000..af6a8397e
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasFileModel.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+
+import { probeImageFileDimensions } from './ImageCanvasFileModel';
+
+function makeFile(bytes: number[], name: string, type: string) {
+  return new File([new Uint8Array(bytes)], name, { type });
+}
+
+function uint16be(value: number) {
+  return [(value >> 8) & 0xff, value & 0xff];
+}
+
+function uint32be(value: number) {
+  return [
+    (value >> 24) & 0xff,
+    (value >> 16) & 0xff,
+    (value >> 8) & 0xff,
+    value & 0xff,
+  ];
+}
+
+function uint16le(value: number) {
+  return [value & 0xff, (value >> 8) & 0xff];
+}
+
+function uint24le(value: number) {
+  return [value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff];
+}
+
+function uint32le(value: number) {
+  return [
+    value & 0xff,
+    (value >> 8) & 0xff,
+    (value >> 16) & 0xff,
+    (value >> 24) & 0xff,
+  ];
+}
+
+describe('ImageCanvasFileModel', () => {
+  it('probes common upload image dimensions from file headers', async () => {
+    const png = makeFile(
+      [
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+        ...uint32be(13),
+        0x49, 0x48, 0x44, 0x52,
+        ...uint32be(1536),
+        ...uint32be(1024),
+        8,
+        6,
+        0,
+        0,
+        0,
+      ],
+      '画布.png',
+      'image/png',
+    );
+    const jpeg = makeFile(
+      [
+        0xff, 0xd8,
+        0xff, 0xe0,
+        ...uint16be(16),
+        0x4a, 0x46, 0x49, 0x46,
+        0, 1, 1, 0, 0, 1, 0, 1, 0, 0,
+        0xff, 0xc0,
+        ...uint16be(17),
+        8,
+        ...uint16be(720),
+        ...uint16be(1280),
+        3,
+        0, 0, 0, 0, 0, 0, 0, 0, 0,
+      ],
+      '画布.jpg',
+      'image/jpeg',
+    );
+    const gif = makeFile(
+      [
+        0x47, 0x49, 0x46, 0x38, 0x39, 0x61,
+        ...uint16le(640),
+        ...uint16le(480),
+        0,
+        0,
+        0,
+      ],
+      '画布.gif',
+      'image/gif',
+    );
+    const webp = makeFile(
+      [
+        0x52, 0x49, 0x46, 0x46,
+        ...uint32le(22),
+        0x57, 0x45, 0x42, 0x50,
+        0x56, 0x50, 0x38, 0x58,
+        ...uint32le(10),
+        0,
+        0,
+        0,
+        0,
+        ...uint24le(799),
+        ...uint24le(599),
+      ],
+      '画布.webp',
+      'image/webp',
+    );
+    const bmp = makeFile(
+      [
+        0x42, 0x4d,
+        ...uint32le(54),
+        0,
+        0,
+        0,
+        0,
+        ...uint32le(54),
+        ...uint32le(40),
+        ...uint32le(300),
+        ...uint32le(200),
+      ],
+      '画布.bmp',
+      'image/bmp',
+    );
+
+    await expect(probeImageFileDimensions(png)).resolves.toEqual({
+      width: 1536,
+      height: 1024,
+    });
+    await expect(probeImageFileDimensions(jpeg)).resolves.toEqual({
+      width: 1280,
+      height: 720,
+    });
+    await expect(probeImageFileDimensions(gif)).resolves.toEqual({
+      width: 640,
+      height: 480,
+    });
+    await expect(probeImageFileDimensions(webp)).resolves.toEqual({
+      width: 800,
+      height: 600,
+    });
+    await expect(probeImageFileDimensions(bmp)).resolves.toEqual({
+      width: 300,
+      height: 200,
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasFileModel.ts b/src/components/image-editor/ImageCanvasFileModel.ts
new file mode 100644
index 000000000..d3264466a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasFileModel.ts
@@ -0,0 +1,456 @@
+export function isImageFile(file: File) {
+  return file.type.startsWith('image/');
+}
+
+export const EDITOR_ASSET_UPLOAD_ACCEPT =
+  'image/*,.mp3,.mp4,audio/mpeg,audio/mp3,video/mp4';
+
+export const SEEDANCE_REFERENCE_ACCEPT = {
+  image:
+    '.jpg,.jpeg,.png,.webp,.bmp,.tiff,.tif,.gif,.heic,.heif,image/jpeg,image/png,image/webp,image/bmp,image/tiff,image/gif,image/heic,image/heif',
+  video: '.mp4,.mov,video/mp4,video/quicktime',
+  audio: '.wav,.mp3,audio/wav,audio/x-wav,audio/mpeg,audio/mp3',
+} as const;
+
+export function getEditorUploadAccept(target: string) {
+  if (target === 'video-reference-video') {
+    return SEEDANCE_REFERENCE_ACCEPT.video;
+  }
+  if (target === 'video-reference-audio') {
+    return SEEDANCE_REFERENCE_ACCEPT.audio;
+  }
+  if (target === 'video-reference-image') {
+    return SEEDANCE_REFERENCE_ACCEPT.image;
+  }
+  return EDITOR_ASSET_UPLOAD_ACCEPT;
+}
+
+export const SEEDANCE_REFERENCE_FILE_LIMITS = {
+  imageBytes: 30 * 1024 * 1024,
+  videoBytes: 50 * 1024 * 1024,
+  audioBytes: 15 * 1024 * 1024,
+  mediaMinDurationSeconds: 2,
+  mediaMaxDurationSeconds: 15,
+  mediaTotalDurationSeconds: 15,
+} as const;
+
+const SEEDANCE_IMAGE_EXTENSIONS = new Set([
+  'jpg',
+  'jpeg',
+  'png',
+  'webp',
+  'bmp',
+  'tiff',
+  'tif',
+  'gif',
+  'heic',
+  'heif',
+]);
+const SEEDANCE_VIDEO_EXTENSIONS = new Set(['mp4', 'mov']);
+const SEEDANCE_AUDIO_EXTENSIONS = new Set(['wav', 'mp3']);
+const EDITOR_ASSET_VIDEO_EXTENSIONS = new Set(['mp4']);
+const EDITOR_ASSET_AUDIO_EXTENSIONS = new Set(['mp3']);
+
+function getFileExtension(file: File) {
+  return file.name.split('.').pop()?.toLowerCase() ?? '';
+}
+
+function hasAllowedExtension(file: File, extensions: Set<string>) {
+  return extensions.has(getFileExtension(file));
+}
+
+export function isSeedanceReferenceImageFile(file: File) {
+  return (
+    (file.type.startsWith('image/') || file.type === '') &&
+    hasAllowedExtension(file, SEEDANCE_IMAGE_EXTENSIONS)
+  );
+}
+
+export function isSeedanceReferenceVideoFile(file: File) {
+  return (
+    (file.type === 'video/mp4' ||
+      file.type === 'video/quicktime' ||
+      file.type === '') &&
+    hasAllowedExtension(file, SEEDANCE_VIDEO_EXTENSIONS)
+  );
+}
+
+export function isSeedanceReferenceAudioFile(file: File) {
+  return (
+    (file.type === 'audio/wav' ||
+      file.type === 'audio/x-wav' ||
+      file.type === 'audio/mpeg' ||
+      file.type === 'audio/mp3' ||
+      file.type === '') &&
+      hasAllowedExtension(file, SEEDANCE_AUDIO_EXTENSIONS)
+  );
+}
+
+export function isEditorAssetVideoFile(file: File) {
+  return (
+    (file.type === 'video/mp4' || file.type === '') &&
+    hasAllowedExtension(file, EDITOR_ASSET_VIDEO_EXTENSIONS)
+  );
+}
+
+export function isEditorAssetAudioFile(file: File) {
+  return (
+    (file.type === 'audio/mpeg' || file.type === 'audio/mp3' || file.type === '') &&
+    hasAllowedExtension(file, EDITOR_ASSET_AUDIO_EXTENSIONS)
+  );
+}
+
+export function resolveEditorAssetUploadMediaType(file: File) {
+  if (isEditorAssetVideoFile(file)) {
+    return 'video' as const;
+  }
+  if (isEditorAssetAudioFile(file)) {
+    return 'audio' as const;
+  }
+  if (isImageFile(file)) {
+    return 'image' as const;
+  }
+  return null;
+}
+
+export function readFileAsDataUrl(file: File) {
+  return new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      if (typeof reader.result === 'string') {
+        resolve(reader.result);
+        return;
+      }
+      reject(new Error('文件读取失败'));
+    };
+    reader.onerror = () => reject(reader.error ?? new Error('文件读取失败'));
+    reader.readAsDataURL(file);
+  });
+}
+
+export function readImageFileAsDataUrl(file: File) {
+  return readFileAsDataUrl(file);
+}
+
+function readBlobAsArrayBuffer(blob: Blob) {
+  if (typeof blob.arrayBuffer === 'function') {
+    return blob.arrayBuffer();
+  }
+  return new Promise<ArrayBuffer>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      if (reader.result instanceof ArrayBuffer) {
+        resolve(reader.result);
+        return;
+      }
+      reject(new Error('文件读取失败'));
+    };
+    reader.onerror = () => reject(reader.error ?? new Error('文件读取失败'));
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+export type ImageFileDimensions = {
+  width: number;
+  height: number;
+};
+
+function readUint24LittleEndian(bytes: Uint8Array, offset: number) {
+  return (
+    byteAt(bytes, offset) +
+    (byteAt(bytes, offset + 1) << 8) +
+    (byteAt(bytes, offset + 2) << 16)
+  );
+}
+
+function byteAt(bytes: Uint8Array, offset: number) {
+  return bytes[offset] ?? 0;
+}
+
+// 中文注释：上传素材需要在创建画布图层和持久化素材前拿到原图 Resolution，避免先写入固定兜底尺寸。
+function parseImageDimensionsFromHeader(
+  buffer: ArrayBuffer,
+): ImageFileDimensions | null {
+  const bytes = new Uint8Array(buffer);
+  const view = new DataView(buffer);
+  if (
+    bytes.length >= 24 &&
+    byteAt(bytes, 0) === 0x89 &&
+    byteAt(bytes, 1) === 0x50 &&
+    byteAt(bytes, 2) === 0x4e &&
+    byteAt(bytes, 3) === 0x47
+  ) {
+    return {
+      width: view.getUint32(16, false),
+      height: view.getUint32(20, false),
+    };
+  }
+  if (
+    bytes.length >= 10 &&
+    byteAt(bytes, 0) === 0x47 &&
+    byteAt(bytes, 1) === 0x49 &&
+    byteAt(bytes, 2) === 0x46
+  ) {
+    return {
+      width: view.getUint16(6, true),
+      height: view.getUint16(8, true),
+    };
+  }
+  if (
+    bytes.length >= 26 &&
+    byteAt(bytes, 0) === 0x42 &&
+    byteAt(bytes, 1) === 0x4d
+  ) {
+    return {
+      width: Math.abs(view.getInt32(18, true)),
+      height: Math.abs(view.getInt32(22, true)),
+    };
+  }
+  if (
+    bytes.length >= 30 &&
+    byteAt(bytes, 0) === 0x52 &&
+    byteAt(bytes, 1) === 0x49 &&
+    byteAt(bytes, 2) === 0x46 &&
+    byteAt(bytes, 3) === 0x46 &&
+    byteAt(bytes, 8) === 0x57 &&
+    byteAt(bytes, 9) === 0x45 &&
+    byteAt(bytes, 10) === 0x42 &&
+    byteAt(bytes, 11) === 0x50
+  ) {
+    const chunkType = String.fromCharCode(
+      byteAt(bytes, 12),
+      byteAt(bytes, 13),
+      byteAt(bytes, 14),
+      byteAt(bytes, 15),
+    );
+    const chunkDataOffset = 20;
+    if (chunkType === 'VP8X' && bytes.length >= 30) {
+      return {
+        width: readUint24LittleEndian(bytes, 24) + 1,
+        height: readUint24LittleEndian(bytes, 27) + 1,
+      };
+    }
+    if (
+      chunkType === 'VP8 ' &&
+      bytes.length >= chunkDataOffset + 10 &&
+      byteAt(bytes, chunkDataOffset + 3) === 0x9d &&
+      byteAt(bytes, chunkDataOffset + 4) === 0x01 &&
+      byteAt(bytes, chunkDataOffset + 5) === 0x2a
+    ) {
+      return {
+        width: view.getUint16(chunkDataOffset + 6, true) & 0x3fff,
+        height: view.getUint16(chunkDataOffset + 8, true) & 0x3fff,
+      };
+    }
+    if (
+      chunkType === 'VP8L' &&
+      bytes.length >= chunkDataOffset + 5 &&
+      byteAt(bytes, chunkDataOffset) === 0x2f
+    ) {
+      const packed =
+        byteAt(bytes, chunkDataOffset + 1) |
+        (byteAt(bytes, chunkDataOffset + 2) << 8) |
+        (byteAt(bytes, chunkDataOffset + 3) << 16) |
+        (byteAt(bytes, chunkDataOffset + 4) << 24);
+      return {
+        width: (packed & 0x3fff) + 1,
+        height: ((packed >> 14) & 0x3fff) + 1,
+      };
+    }
+  }
+  if (
+    bytes.length >= 4 &&
+    byteAt(bytes, 0) === 0xff &&
+    byteAt(bytes, 1) === 0xd8
+  ) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+      if (byteAt(bytes, offset) !== 0xff) {
+        offset += 1;
+        continue;
+      }
+      const marker = byteAt(bytes, offset + 1);
+      if (marker === 0xd8 || marker === 0xd9) {
+        offset += 2;
+        continue;
+      }
+      const segmentLength = view.getUint16(offset + 2, false);
+      if (segmentLength < 2 || offset + 2 + segmentLength > bytes.length) {
+        break;
+      }
+      if (
+        (marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf)
+      ) {
+        return {
+          height: view.getUint16(offset + 5, false),
+          width: view.getUint16(offset + 7, false),
+        };
+      }
+      offset += 2 + segmentLength;
+    }
+  }
+  return null;
+}
+
+const HEADER_DIMENSION_IMAGE_TYPES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/jpg',
+  'image/webp',
+  'image/gif',
+  'image/bmp',
+  'image/x-ms-bmp',
+]);
+
+function hasSupportedImageHeaderSignature(buffer: ArrayBuffer) {
+  const bytes = new Uint8Array(buffer);
+  return (
+    (bytes.length >= 4 &&
+      byteAt(bytes, 0) === 0x89 &&
+      byteAt(bytes, 1) === 0x50 &&
+      byteAt(bytes, 2) === 0x4e &&
+      byteAt(bytes, 3) === 0x47) ||
+    (bytes.length >= 3 &&
+      byteAt(bytes, 0) === 0x47 &&
+      byteAt(bytes, 1) === 0x49 &&
+      byteAt(bytes, 2) === 0x46) ||
+    (bytes.length >= 2 &&
+      byteAt(bytes, 0) === 0x42 &&
+      byteAt(bytes, 1) === 0x4d) ||
+    (bytes.length >= 12 &&
+      byteAt(bytes, 0) === 0x52 &&
+      byteAt(bytes, 1) === 0x49 &&
+      byteAt(bytes, 2) === 0x46 &&
+      byteAt(bytes, 3) === 0x46 &&
+      byteAt(bytes, 8) === 0x57 &&
+      byteAt(bytes, 9) === 0x45 &&
+      byteAt(bytes, 10) === 0x42 &&
+      byteAt(bytes, 11) === 0x50) ||
+    (bytes.length >= 2 &&
+      byteAt(bytes, 0) === 0xff &&
+      byteAt(bytes, 1) === 0xd8)
+  );
+}
+
+function normalizeImageFileDimensions(
+  dimensions: ImageFileDimensions | null,
+) {
+  if (
+    !dimensions ||
+    dimensions.width <= 0 ||
+    dimensions.height <= 0 ||
+    !Number.isFinite(dimensions.width) ||
+    !Number.isFinite(dimensions.height)
+  ) {
+    return null;
+  }
+  return {
+    width: Math.round(dimensions.width),
+    height: Math.round(dimensions.height),
+  };
+}
+
+async function probeImageDimensionsWithBrowserDecode(file: File) {
+  if (typeof createImageBitmap === 'function') {
+    try {
+      const bitmap = await createImageBitmap(file);
+      const dimensions = { width: bitmap.width, height: bitmap.height };
+      bitmap.close();
+      return normalizeImageFileDimensions(dimensions);
+    } catch {
+      return null;
+    }
+  }
+  if (
+    typeof Image === 'undefined' ||
+    typeof URL === 'undefined' ||
+    typeof URL.createObjectURL !== 'function'
+  ) {
+    return null;
+  }
+  return new Promise<ImageFileDimensions | null>((resolve) => {
+    const objectUrl = URL.createObjectURL(file);
+    const image = new Image();
+    let settled = false;
+    const cleanup = () => {
+      if (typeof URL.revokeObjectURL === 'function') {
+        URL.revokeObjectURL(objectUrl);
+      }
+    };
+    const finish = (dimensions: ImageFileDimensions | null) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      cleanup();
+      resolve(dimensions);
+    };
+    const timeout = setTimeout(() => finish(null), 180);
+    image.onload = () => {
+      finish(
+        normalizeImageFileDimensions({
+          width: image.naturalWidth || image.width,
+          height: image.naturalHeight || image.height,
+        }),
+      );
+    };
+    image.onerror = () => {
+      finish(null);
+    };
+    image.src = objectUrl;
+  });
+}
+
+export async function probeImageFileDimensions(file: File) {
+  const headerBuffer = await readBlobAsArrayBuffer(file.slice(0, 65_536));
+  const headerDimensions = normalizeImageFileDimensions(
+    parseImageDimensionsFromHeader(headerBuffer),
+  );
+  if (headerDimensions) {
+    return headerDimensions;
+  }
+  if (
+    HEADER_DIMENSION_IMAGE_TYPES.has(file.type.toLowerCase()) &&
+    !hasSupportedImageHeaderSignature(headerBuffer)
+  ) {
+    return null;
+  }
+  return probeImageDimensionsWithBrowserDecode(file);
+}
+
+export function probeMediaDurationSeconds(
+  file: File,
+  mediaType: 'video' | 'audio',
+) {
+  return new Promise<number>((resolve, reject) => {
+    if (typeof document === 'undefined' || typeof URL === 'undefined') {
+      resolve(Number.NaN);
+      return;
+    }
+    const element =
+      mediaType === 'video'
+        ? document.createElement('video')
+        : document.createElement('audio');
+    const objectUrl = URL.createObjectURL(file);
+    const cleanup = () => {
+      URL.revokeObjectURL(objectUrl);
+      element.removeAttribute('src');
+      element.load();
+    };
+    element.preload = 'metadata';
+    element.onloadedmetadata = () => {
+      const duration = element.duration;
+      cleanup();
+      resolve(duration);
+    };
+    element.onerror = () => {
+      cleanup();
+      reject(new Error('读取媒体时长失败'));
+    };
+    element.src = objectUrl;
+  });
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx b/src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx
new file mode 100644
index 000000000..1f4d0f55c
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx
@@ -0,0 +1,710 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import {
+  type ComponentProps,
+  createRef,
+  type Dispatch,
+  type SetStateAction,
+  useState,
+} from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationComposerView } from './ImageCanvasGenerationComposerView';
+
+function mockStateSetter<T>() {
+  return vi.fn() as unknown as Dispatch<SetStateAction<T>>;
+}
+
+
+function createComposerProps(
+  generateDialog: GenerateDialogState,
+  overrides: Partial<
+    ComponentProps<typeof ImageCanvasGenerationComposerView>
+  > = {},
+): ComponentProps<typeof ImageCanvasGenerationComposerView> {
+  return {
+    specToolWrapRef: createRef(),
+    characterSpecButtonRef: createRef(),
+    characterReferenceButtonRef: createRef(),
+    generationReferenceButtonRef: createRef(),
+    iconSpecButtonRef: createRef(),
+    publicationReferenceButtonRef: createRef(),
+    isSpecMenuOpen: false,
+    isCharacterSpecMenuOpen: false,
+    isCharacterReferenceMenuOpen: false,
+    isGenerationReferenceMenuOpen: false,
+    isIconSpecMenuOpen: false,
+    isUiDesignSpecMenuOpen: false,
+    isPublicationReferenceMenuOpen: false,
+    isPickingCharacterSpecFromCanvas: false,
+    isPickingCharacterReferenceFromCanvas: false,
+    isPickingGenerationReferenceFromCanvas: false,
+    isPickingQuickEditReferenceFromCanvas: false,
+    isPickingIconSpecFromCanvas: false,
+    isPickingUiDesignSpecFromCanvas: false,
+    isPickingPublicationReferenceFromCanvas: false,
+    generateDialog,
+    generationComposerStyle: { left: 320, top: 240 },
+    iconComposerStyle: { left: 320, top: 240, width: '32rem' },
+    quickEditPanel: null,
+    quickEditSourceLayer: null,
+    quickEditPanelStyle: null,
+    cropExpandPanel: null,
+    cropExpandSourceLayer: null,
+    cropExpandPanelStyle: null,
+    characterAnimationPanel: null,
+    characterAnimationSourceLayer: null,
+    characterAnimationPanelStyle: null,
+    characterAnimationPrice: 40,
+    setGenerateDialog: mockStateSetter<GenerateDialogState | null>(),
+    setQuickEditPanel:
+      mockStateSetter<
+        ComponentProps<
+          typeof ImageCanvasGenerationComposerView
+        >['quickEditPanel']
+      >(),
+    setCropExpandPanel:
+      mockStateSetter<
+        ComponentProps<
+          typeof ImageCanvasGenerationComposerView
+        >['cropExpandPanel']
+      >(),
+    setCharacterAnimationPanel:
+      mockStateSetter<
+        ComponentProps<
+          typeof ImageCanvasGenerationComposerView
+        >['characterAnimationPanel']
+      >(),
+    setIsCharacterSpecMenuOpen: mockStateSetter<boolean>(),
+    setIsCharacterReferenceMenuOpen: mockStateSetter<boolean>(),
+    setIsGenerationReferenceMenuOpen: mockStateSetter<boolean>(),
+    setIsPickingQuickEditReferenceFromCanvas: mockStateSetter<boolean>(),
+    setIsIconSpecMenuOpen: mockStateSetter<boolean>(),
+    setIsUiDesignSpecMenuOpen: mockStateSetter<boolean>(),
+    setIsPublicationReferenceMenuOpen: mockStateSetter<boolean>(),
+    setIsPickingCharacterSpecFromCanvas: mockStateSetter<boolean>(),
+    setIsPickingCharacterReferenceFromCanvas: mockStateSetter<boolean>(),
+    setIsPickingGenerationReferenceFromCanvas: mockStateSetter<boolean>(),
+    setIsPickingIconSpecFromCanvas: mockStateSetter<boolean>(),
+    setIsPickingUiDesignSpecFromCanvas: mockStateSetter<boolean>(),
+    setIsPickingPublicationReferenceFromCanvas: mockStateSetter<boolean>(),
+    onOpenSpecDialog: vi.fn(),
+    onRequestUpload: vi.fn(),
+    onSubmitImageGeneration: vi.fn(),
+    onSubmitIconSpritesheetGeneration: vi.fn(),
+    onSubmitQuickEdit: vi.fn(),
+    onSubmitCropExpand: vi.fn(),
+    onSubmitCharacterAnimation: vi.fn(),
+    onUpdateSpecFormValue: vi.fn(),
+    onUpdateIconDescriptionText: vi.fn(),
+    onUpdateCharacterAnimationDuration: vi.fn(),
+    onRememberImageModel: vi.fn(),
+    ...overrides,
+  };
+}
+
+function renderComposer(
+  generateDialog: GenerateDialogState,
+  overrides: Partial<
+    ComponentProps<typeof ImageCanvasGenerationComposerView>
+  > = {},
+) {
+  const props = createComposerProps(generateDialog, overrides);
+
+  return render(<ImageCanvasGenerationComposerView {...props} />);
+}
+
+describe('ImageCanvasGenerationComposerView', () => {
+  it('让生成UI设计图面板复用普通图片生成面板的纵向结构', () => {
+    const setGenerateDialog = vi.fn();
+    renderComposer({
+      mode: 'ui-design',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+      uiDesignSpecReference: null,
+      imageModel: 'gpt-image-2',
+      aspectRatio: '16:9',
+      imageSize: '1K',
+    }, {
+      isUiDesignSpecMenuOpen: true,
+      setGenerateDialog:
+        setGenerateDialog as unknown as Dispatch<
+          SetStateAction<GenerateDialogState | null>
+        >,
+    });
+
+    const panel = screen.getByRole('dialog', { name: '生成UI设计图' });
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    expect(panel.className).toContain(
+      'image-canvas-editor__generation-composer',
+    );
+    expect(panel.className).toContain(
+      'image-canvas-editor__generation-composer--image',
+    );
+    expect(
+      within(panel).getByRole('button', { name: 'UI设计图标规范' }),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('textbox', { name: 'UI设计要求' }).className,
+    ).toContain('image-canvas-editor__generation-prompt');
+    expect(
+      panel.querySelector('.image-canvas-editor__generation-composer-footer'),
+    ).toBeTruthy();
+    fireEvent.change(within(panel).getByRole('textbox', { name: 'UI设计要求' }), {
+      target: { value: '主界面和结算弹窗' },
+    });
+    expect(setGenerateDialog).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', { name: '参考图来源' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '新建图标规范' }),
+    ).toBeTruthy();
+  });
+
+  it('让生成规范图片面板复用生成类面板 shell 和底部按钮结构', () => {
+    renderComposer({
+      mode: 'spec',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+      specType: 'character',
+      specValues: {
+        playSetting: '战棋类RPG玩法',
+        artStyle: '像素风',
+        bodyRatio: '3',
+        characterView: '右向斜侧身站姿',
+        customPrompt: '',
+      },
+      specReference: null,
+    });
+
+    const panel = screen.getByRole('dialog', { name: '生成规范' });
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    expect(panel.className).toContain(
+      'image-canvas-editor__generation-composer',
+    );
+    expect(panel.className).toContain(
+      'image-canvas-editor__generation-composer--image',
+    );
+    expect(within(panel).getByRole('button', { name: '参考图' })).toBeTruthy();
+    expect(
+      panel.querySelector('.image-canvas-editor__generation-composer-footer'),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', { name: '提交生成规范' }).className,
+    ).toContain('image-canvas-editor__generation-submit');
+  });
+
+  it('让图标规范生成面板也保留首行参考区', () => {
+    renderComposer({
+      mode: 'spec',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+      specType: 'icon',
+      specValues: {
+        playSetting: '休闲小游戏',
+        artStyle: '清爽卡通',
+        bodyRatio: '3',
+        characterView: '右向斜侧身站姿',
+        customPrompt: '',
+      },
+      specReference: null,
+    });
+
+    const panel = screen.getByRole('dialog', { name: '生成规范' });
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    expect(within(panel).getByRole('button', { name: '参考图' })).toBeTruthy();
+  });
+
+  it.each([
+    ['publication-cover-image', '游戏首图', '720 x 540'],
+    ['publication-detail-gallery', '详情五图', '720 x 1280'],
+    ['publication-promo-poster', '运营海报', '1280 x 720'],
+  ] as const)('让%s 宣发素材面板对齐生成角色面板结构', (workflowId, label, sizeLabel) => {
+    renderComposer({
+      mode: 'publication',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+      publicationWorkflowId: workflowId,
+      publicationGameInfo: {
+        gameName: '',
+        gameCategories: '',
+        gameDescription: '',
+      },
+      publicationReferences: [],
+      imageModel: 'gpt-image-2',
+      aspectRatio: '16:9',
+      imageSize: '1K',
+    });
+
+    const panel = screen.getByRole('dialog', { name: `${label}生成卡片` });
+    expect(panel.className).toContain('image-canvas-editor__character-composer');
+    expect(panel.className).toContain('image-canvas-editor__publication-composer');
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    expect(within(panel).getByRole('button', { name: '添加参考图' })).toBeTruthy();
+    expect(
+      within(panel).getByRole('textbox', { name: `${label}游戏名` }),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('textbox', { name: `${label}一句话描述游戏` }),
+    ).toBeTruthy();
+    expect(panel.textContent).toContain(sizeLabel);
+    expect(
+      panel.querySelector('.image-canvas-editor__generation-composer-footer'),
+    ).toBeTruthy();
+    expect(within(panel).getByRole('button', { name: '生成' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('恢复宣发素材生成卡片的字段和参考图', () => {
+    renderComposer({
+      mode: 'publication',
+      prompt: '马戏团午夜惊魂｜非对称对抗｜找到钥匙逃离',
+      status: 'idle',
+      composerOpen: true,
+      publicationWorkflowId: 'publication-promo-poster',
+      publicationGameInfo: {
+        gameName: '马戏团午夜惊魂',
+        gameCategories: '非对称对抗',
+        gameDescription: '找到钥匙，开门逃离马戏团',
+      },
+      publicationReferences: [
+        {
+          id: 'publication-reference-1',
+          label: '首图参考',
+          src: '/generated-character-drafts/editor/reference.png',
+        },
+      ],
+      imageModel: 'gpt-image-2',
+      aspectRatio: '16:9',
+      imageSize: '2K',
+    });
+
+    const panel = screen.getByRole('dialog', { name: '运营海报生成卡片' });
+    expect(
+      (within(panel).getByRole('textbox', {
+        name: '运营海报游戏名',
+      }) as HTMLInputElement).value,
+    ).toBe('马戏团午夜惊魂');
+    expect(
+      (within(panel).getByRole('textbox', {
+        name: '运营海报游戏分类',
+      }) as HTMLInputElement).value,
+    ).toBe('非对称对抗');
+    expect(
+      (within(panel).getByRole('textbox', {
+        name: '运营海报一句话描述游戏',
+      }) as HTMLTextAreaElement).value,
+    ).toBe('找到钥匙，开门逃离马戏团');
+    expect(within(panel).getByLabelText('首图参考')).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', { name: '删除首图参考' }),
+    ).toBeTruthy();
+  });
+
+  it('生成图片参考图点击先弹来源菜单，不直接打开上传', () => {
+    const onRequestUpload = vi.fn();
+    const setIsGenerationReferenceMenuOpen = vi.fn();
+
+    renderComposer(
+      {
+        mode: 'generate',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        generationReferences: [],
+      },
+      {
+        isGenerationReferenceMenuOpen: true,
+        onRequestUpload,
+        setIsGenerationReferenceMenuOpen,
+      },
+    );
+
+    const panel = screen.getByRole('dialog', { name: '生成图片' });
+    fireEvent.click(within(panel).getByRole('button', { name: '添加参考图' }));
+
+    expect(onRequestUpload).not.toHaveBeenCalled();
+    expect(setIsGenerationReferenceMenuOpen).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', { name: '参考图来源' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '从画布中选择' }),
+    ).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '上传图片' }),
+    ).toBeTruthy();
+  });
+
+  it('生成视频参考图点击先弹来源菜单，不直接打开上传', () => {
+    const onRequestUpload = vi.fn();
+    const setIsGenerationReferenceMenuOpen = vi.fn();
+
+    renderComposer(
+      {
+        mode: 'video',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        generationReferences: [],
+        videoModel: 'seedance2.0-fast',
+        videoAspectRatio: '16:9',
+        videoDurationSeconds: 4,
+        videoResolution: '480p',
+        videoMode: 'std',
+        videoSound: 'off',
+      },
+      {
+        isGenerationReferenceMenuOpen: true,
+        onRequestUpload,
+        setIsGenerationReferenceMenuOpen,
+      },
+    );
+
+    const panel = screen.getByRole('dialog', { name: '生成视频' });
+    fireEvent.click(
+      within(panel).getByRole('button', { name: '添加视频参考素材' }),
+    );
+
+    expect(onRequestUpload).not.toHaveBeenCalled();
+    expect(setIsGenerationReferenceMenuOpen).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', { name: '参考素材来源' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '从画布中选择' }),
+    ).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '上传图片' }),
+    ).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '上传视频' }),
+    ).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '上传音频' }),
+    ).toBeTruthy();
+  });
+
+  it('点击生成视频父级面板任意区域会收起参考素材菜单', () => {
+    function VideoReferenceMenuHarness() {
+      const [isGenerationReferenceMenuOpen, setIsGenerationReferenceMenuOpen] =
+        useState(true);
+      const dialog: GenerateDialogState = {
+        mode: 'video',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        generationReferences: [],
+        videoModel: 'seedance2.0-fast',
+        videoAspectRatio: '16:9',
+        videoDurationSeconds: 4,
+        videoResolution: '480p',
+        videoMode: 'std',
+        videoSound: 'off',
+      };
+
+      return (
+        <ImageCanvasGenerationComposerView
+          {...createComposerProps(dialog)}
+          isGenerationReferenceMenuOpen={isGenerationReferenceMenuOpen}
+          setIsGenerationReferenceMenuOpen={setIsGenerationReferenceMenuOpen}
+        />
+      );
+    }
+
+    render(<VideoReferenceMenuHarness />);
+
+    expect(screen.getByRole('menu', { name: '参考素材来源' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('textbox', { name: '视频描述' }));
+
+    expect(screen.queryByRole('menu', { name: '参考素材来源' })).toBeNull();
+  });
+
+  it('生成视频面板用子面板修改参数和模型，不展示 Veo，并在按钮内显示泥点文案', () => {
+    function VideoHarness() {
+      const [dialog, setDialog] = useState<GenerateDialogState>({
+        mode: 'video',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        generationReferences: [],
+        videoModel: 'seedance2.0-fast',
+        videoAspectRatio: '16:9',
+        videoDurationSeconds: 4,
+        videoResolution: '480p',
+        videoMode: 'std',
+        videoSound: 'off',
+        placeholder: {
+          x: 53,
+          y: 120,
+          width: 854,
+          height: 480,
+          originalWidth: 854,
+          originalHeight: 480,
+        },
+      });
+      return (
+        <>
+          <ImageCanvasGenerationComposerView
+            {...createComposerProps(dialog)}
+            setGenerateDialog={setDialog as Dispatch<SetStateAction<GenerateDialogState | null>>}
+          />
+          <output aria-label="当前视频模型">{dialog.videoModel}</output>
+          <output aria-label="当前视频时长">{dialog.videoDurationSeconds}</output>
+          <output aria-label="当前视频清晰度">{dialog.videoResolution}</output>
+          <output aria-label="当前视频占位">
+            {dialog.placeholder
+              ? [
+                  dialog.placeholder.x,
+                  dialog.placeholder.y,
+                  dialog.placeholder.width,
+                  dialog.placeholder.height,
+                  dialog.placeholder.originalWidth,
+                  dialog.placeholder.originalHeight,
+                ].join(':')
+              : '-'}
+          </output>
+        </>
+      );
+    }
+
+    render(<VideoHarness />);
+
+    const panel = screen.getByRole('dialog', { name: '生成视频' });
+    expect(
+      within(panel).getByRole('button', {
+        name: '视频参数 16:9 · 4秒 · 480p',
+      }),
+    ).toBeTruthy();
+    expect(
+      within(panel).getByRole('button', { name: '模型 Seedance 2.0 Fast' }),
+    ).toBeTruthy();
+    expect(within(panel).getByRole('button', { name: '生成视频' }).textContent).toBe(
+      '生成40泥点',
+    );
+
+    fireEvent.click(
+      within(panel).getByRole('button', {
+        name: '视频参数 16:9 · 4秒 · 480p',
+      }),
+    );
+    const paramsPanel = screen.getByRole('menu', {
+      name: '视频参数选项',
+    });
+    fireEvent.change(within(paramsPanel).getByRole('slider', { name: '视频时长' }), {
+      target: { value: '5' },
+    });
+    fireEvent.click(within(paramsPanel).getByRole('button', { name: '清晰度 720p' }));
+    fireEvent.click(within(paramsPanel).getByRole('button', { name: '静音' }));
+
+    expect(
+      screen.getByRole('menu', { name: '视频参数选项' }),
+    ).toBeTruthy();
+    expect(screen.getByLabelText('当前视频时长').textContent).toBe('5');
+    expect(screen.getByLabelText('当前视频清晰度').textContent).toBe('720p');
+    expect(screen.getByLabelText('当前视频占位').textContent).toBe(
+      '-160:0:1280:720:1280:720',
+    );
+    expect(
+      screen.getByRole('button', { name: '视频参数 16:9 · 5秒 · 720p' }),
+    ).toBeTruthy();
+    expect(
+      within(paramsPanel)
+        .getByRole('button', { name: '清晰度 1080p' })
+        .hasAttribute('disabled'),
+    ).toBe(true);
+    expect(screen.getByRole('button', { name: '生成视频' }).textContent).toBe(
+      '生成100泥点',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '模型 Seedance 2.0 Fast' }));
+    const modelPanel = screen.getByRole('menu', { name: '视频模型选项' });
+    expect(within(modelPanel).queryByRole('button', { name: /Veo/i })).toBeNull();
+    fireEvent.click(within(modelPanel).getByRole('button', { name: 'Kling 3.0' }));
+
+    expect(screen.getByRole('menu', { name: '视频模型选项' })).toBeTruthy();
+    expect(screen.getByLabelText('当前视频模型').textContent).toBe('kling3.0');
+    expect(screen.getByRole('button', { name: '模型 Kling 3.0' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: '生成视频' }).textContent).toBe(
+      '生成150泥点',
+    );
+  });
+
+  it('生成游戏音效面板使用 Vidu duration 参数且不再显示类型和 BPM', () => {
+    const onSubmitImageGeneration = vi.fn();
+    function AudioHarness() {
+      const [dialog, setDialog] = useState<GenerateDialogState>({
+        mode: 'audio-sound-effect',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        soundModel: 'audio1.0',
+        soundDurationSeconds: 5,
+      });
+      return (
+        <>
+          <ImageCanvasGenerationComposerView
+            {...createComposerProps(dialog, { onSubmitImageGeneration })}
+            setGenerateDialog={
+              setDialog as Dispatch<SetStateAction<GenerateDialogState | null>>
+            }
+          />
+          <output aria-label="当前音效模型">{dialog.soundModel}</output>
+          <output aria-label="当前音效时长">
+            {dialog.soundDurationSeconds ?? 'null'}
+          </output>
+        </>
+      );
+    }
+
+    render(<AudioHarness />);
+
+    const panel = screen.getByRole('dialog', { name: '生成游戏音效' });
+    const footer = panel.querySelector(
+      '.image-canvas-editor__generation-composer-footer',
+    );
+    expect(footer).toBeTruthy();
+    expect(footer?.children[0]?.className).toContain(
+      'image-canvas-editor__option-popover-anchor--dimensions',
+    );
+    expect(footer?.children[1]?.className).toContain(
+      'image-canvas-editor__option-popover-anchor--model',
+    );
+    expect(footer?.children[2]?.className).toContain(
+      'image-canvas-editor__generation-submit',
+    );
+    expect(within(panel).getByRole('textbox', { name: 'prompt' })).toBeTruthy();
+    expect(screen.getByLabelText('当前音效模型').textContent).toBe('audio1.0');
+    const soundModelButton = within(panel).getByRole('button', {
+      name: '音效模型 Vidu',
+    });
+    expect((soundModelButton as HTMLButtonElement).disabled).toBe(true);
+    expect(within(panel).getByText('Vidu')).toBeTruthy();
+    expect(within(panel).queryByText(/Suno/u)).toBeNull();
+    expect(
+      within(panel).getByRole('button', { name: '音效时长 5秒' }),
+    ).toBeTruthy();
+    expect(within(panel).queryByText('单次')).toBeNull();
+    expect(within(panel).queryByText('循环')).toBeNull();
+    expect(within(panel).queryByText(/BPM/u)).toBeNull();
+    expect(within(panel).getByRole('button', { name: '生成游戏音效' }).textContent).toBe(
+      '生成10泥点',
+    );
+
+    fireEvent.click(
+      within(panel).getByRole('button', { name: '音效时长 5秒' }),
+    );
+    const optionPanel = screen.getByRole('menu', { name: '音效时长选项' });
+    expect(
+      within(optionPanel).getByRole('button', { name: '时长 2秒' }),
+    ).toBeTruthy();
+    expect(
+      within(optionPanel).getByRole('button', { name: '时长 10秒' }),
+    ).toBeTruthy();
+    expect(within(optionPanel).queryByText(/BPM/u)).toBeNull();
+    fireEvent.click(within(optionPanel).getByRole('button', { name: '时长 8秒' }));
+
+    expect(screen.getByLabelText('当前音效时长').textContent).toBe('8');
+    expect(
+      screen.getByRole('button', { name: '音效时长 8秒' }),
+    ).toBeTruthy();
+
+    fireEvent.submit(panel);
+    expect(onSubmitImageGeneration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mode: 'audio-sound-effect',
+        soundDurationSeconds: 8,
+      }),
+    );
+  });
+
+  it('生成游戏背景音乐面板只展示 gpt_description_prompt 并固定隐藏 instrumental 开关', () => {
+    renderComposer({
+      mode: 'audio-background-music',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+    });
+
+    const panel = screen.getByRole('dialog', { name: '生成游戏背景音乐' });
+    expect(
+      within(panel).getByRole('textbox', { name: 'gpt_description_prompt' }),
+    ).toBeTruthy();
+    const footer = panel.querySelector(
+      '.image-canvas-editor__generation-composer-footer',
+    );
+    expect(footer).toBeTruthy();
+    expect(footer?.children[0]?.className).toContain(
+      'image-canvas-editor__option-popover-anchor--model',
+    );
+    expect(footer?.children[1]?.className).toContain(
+      'image-canvas-editor__generation-submit',
+    );
+    const backgroundMusicModelButton = within(panel).getByRole('button', {
+      name: '背景音乐模型 Suno',
+    });
+    expect((backgroundMusicModelButton as HTMLButtonElement).disabled).toBe(
+      true,
+    );
+    expect(within(panel).getByText('Suno')).toBeTruthy();
+    expect(within(panel).queryByText('make_instrumental')).toBeNull();
+    expect(within(panel).getByRole('button', { name: '生成游戏背景音乐' }).textContent).toBe(
+      '生成5泥点',
+    );
+  });
+  it('生成规范参考图点击先弹来源菜单，不直接打开上传', () => {
+    const onRequestUpload = vi.fn();
+    const setIsGenerationReferenceMenuOpen = vi.fn();
+
+    renderComposer(
+      {
+        mode: 'spec',
+        prompt: '',
+        status: 'idle',
+        composerOpen: true,
+        specType: 'character',
+        specValues: {
+          playSetting: '战棋类RPG玩法',
+          artStyle: '像素风',
+          bodyRatio: '3',
+          characterView: '右向斜侧身站姿',
+          customPrompt: '',
+        },
+        specReference: null,
+      },
+      {
+        isGenerationReferenceMenuOpen: true,
+        onRequestUpload,
+        setIsGenerationReferenceMenuOpen,
+      },
+    );
+
+    const panel = screen.getByRole('dialog', { name: '生成规范' });
+    fireEvent.click(within(panel).getByRole('button', { name: '参考图' }));
+
+    expect(onRequestUpload).not.toHaveBeenCalled();
+    expect(setIsGenerationReferenceMenuOpen).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', { name: '参考图来源' });
+    expect(within(menu).getByRole('menuitem', { name: '从画布中选择' })).toBeTruthy();
+    expect(within(menu).getByRole('menuitem', { name: '上传图片' })).toBeTruthy();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationComposerView.tsx b/src/components/image-editor/ImageCanvasGenerationComposerView.tsx
new file mode 100644
index 000000000..3ab848b96
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationComposerView.tsx
@@ -0,0 +1,1235 @@
+import { Check, ChevronDown, Cpu, Film, ImageIcon, Music } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { ImageCanvasBasicGenerationComposerView } from './ImageCanvasBasicGenerationComposerView';
+import { ImageCanvasCharacterAnimationPanelView } from './ImageCanvasCharacterAnimationPanelView';
+import { ImageCanvasCharacterGenerationComposerView } from './ImageCanvasCharacterGenerationComposerView';
+import { ImageCanvasCropExpandPanelView } from './ImageCanvasCropExpandPanelView';
+import { ImageCanvasEditGenerationModalView } from './ImageCanvasEditGenerationModalView';
+import type {
+  CanvasLayer,
+  CharacterAnimationPanelState,
+  CropExpandPanelState,
+  GenerateDialogState,
+  QuickEditPanelState,
+  SpecFormValues,
+  SpecGenerationType,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import {
+  calculateEditorBackgroundMusicPrice,
+  calculateEditorSoundEffectPrice,
+  calculateEditorVideoPrice,
+  DEFAULT_BACKGROUND_MUSIC_MODEL,
+  DEFAULT_SOUND_EFFECT_DURATION_SECONDS,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  DEFAULT_VIDEO_ASPECT_RATIO,
+  DEFAULT_VIDEO_DURATION_SECONDS,
+  DEFAULT_VIDEO_SOUND,
+  DEFAULT_VIDEO_WEB_SEARCH_ENABLED,
+  EDITOR_VIDEO_ASPECT_RATIO_OPTIONS,
+  EDITOR_SOUND_EFFECT_MODEL_OPTIONS,
+  SOUND_EFFECT_DURATION_OPTIONS,
+  EDITOR_VIDEO_MODEL_OPTIONS,
+  EDITOR_VIDEO_RESOLUTION_OPTIONS,
+  VIDEO_MODEL_SEEDANCE_2_FAST,
+  resizeGenerationPlaceholderToVideoSelection,
+  SPEC_TYPE_LABEL,
+} from './ImageCanvasGenerationModel';
+import { ImageCanvasIconSpritesheetComposerView } from './ImageCanvasIconSpritesheetComposerView';
+import { ImageCanvasPublicationMaterialsDemoPanelView } from './ImageCanvasPublicationMaterialsDemoPanelView';
+import { getPublicationMaterialsWorkflow } from './ImageCanvasPublicationMaterialsModel';
+import { ImageCanvasQuickEditPanelView } from './ImageCanvasQuickEditPanelView';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import { ImageCanvasSpecGenerationPanelView } from './ImageCanvasSpecGenerationPanelView';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasGenerationComposerViewProps = {
+  specToolWrapRef: RefObject<HTMLSpanElement | null>;
+  publicationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  characterSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  characterReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  generationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  iconSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  isSpecMenuOpen: boolean;
+  isGenerationReferenceMenuOpen: boolean;
+  isPublicationReferenceMenuOpen: boolean;
+  isCharacterSpecMenuOpen: boolean;
+  isCharacterReferenceMenuOpen: boolean;
+  isIconSpecMenuOpen: boolean;
+  isUiDesignSpecMenuOpen: boolean;
+  isPickingGenerationReferenceFromCanvas: boolean;
+  isPickingQuickEditReferenceFromCanvas: boolean;
+  isPickingPublicationReferenceFromCanvas: boolean;
+  isPickingCharacterSpecFromCanvas: boolean;
+  isPickingCharacterReferenceFromCanvas: boolean;
+  isPickingIconSpecFromCanvas: boolean;
+  isPickingUiDesignSpecFromCanvas: boolean;
+  generateDialog: GenerateDialogState | null;
+  generationComposerStyle: CSSProperties | null;
+  iconComposerStyle: CSSProperties | null;
+  quickEditPanel: QuickEditPanelState | null;
+  quickEditSourceLayer: CanvasLayer | null;
+  quickEditPanelStyle: CSSProperties | null;
+  cropExpandPanel: CropExpandPanelState | null;
+  cropExpandSourceLayer: CanvasLayer | null;
+  cropExpandPanelStyle: CSSProperties | null;
+  characterAnimationPanel: CharacterAnimationPanelState | null;
+  characterAnimationSourceLayer: CanvasLayer | null;
+  characterAnimationPanelStyle: CSSProperties | null;
+  characterAnimationPrice: number;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setQuickEditPanel: Dispatch<SetStateAction<QuickEditPanelState | null>>;
+  setCropExpandPanel: Dispatch<SetStateAction<CropExpandPanelState | null>>;
+  setCharacterAnimationPanel: Dispatch<
+    SetStateAction<CharacterAnimationPanelState | null>
+  >;
+  setIsGenerationReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPublicationReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsCharacterSpecMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsCharacterReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsIconSpecMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsUiDesignSpecMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPickingGenerationReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingQuickEditReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingPublicationReferenceFromCanvas: Dispatch<
+    SetStateAction<boolean>
+  >;
+  setIsPickingCharacterSpecFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingCharacterReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingIconSpecFromCanvas: Dispatch<SetStateAction<boolean>>;
+  setIsPickingUiDesignSpecFromCanvas: Dispatch<SetStateAction<boolean>>;
+  onOpenSpecDialog: (specType: SpecGenerationType) => void;
+  onRequestUpload: (target: UploadTarget) => void;
+  onSubmitImageGeneration: (dialog: GenerateDialogState) => void;
+  onSubmitIconSpritesheetGeneration: (dialog: GenerateDialogState) => void;
+  onSubmitQuickEdit: () => void;
+  onSubmitCropExpand: () => void;
+  onSubmitCharacterAnimation: () => void;
+  onUpdateSpecFormValue: (key: keyof SpecFormValues, value: string) => void;
+  onUpdateIconDescriptionText: (value: string) => void;
+  onUpdateCharacterAnimationDuration: (frameCountValue: string) => void;
+  onRememberImageModel: (model: string) => void;
+  onSpecMenuPointerEnter?: () => void;
+  onSpecMenuPointerLeave?: () => void;
+};
+
+function buildPortalMenuStyle(
+  anchor: HTMLElement | null,
+  placement: 'above' | 'below',
+): CSSProperties {
+  const rect = anchor?.getBoundingClientRect();
+  if (!rect) {
+    return {
+      position: 'fixed',
+      left: 0,
+      top: 0,
+      right: 'auto',
+      bottom: 'auto',
+      zIndex: 70,
+    };
+  }
+
+  return {
+    position: 'fixed',
+    left: Math.round(rect.left),
+    top:
+      placement === 'above'
+        ? Math.round(rect.top)
+        : Math.round(rect.bottom + 8),
+    right: 'auto',
+    bottom: 'auto',
+    zIndex: 70,
+    transform:
+      placement === 'above' ? 'translateY(calc(-100% - 0.45rem))' : undefined,
+  };
+}
+
+function renderEditorPortal(node: ReactNode) {
+  if (typeof document === 'undefined') {
+    return node;
+  }
+  return createPortal(node, document.body);
+}
+
+function resetFailedVideoDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function isSeedanceVideoModel(model: string | undefined) {
+  return model === 'seedance2.0' || model === 'seedance2.0-fast';
+}
+
+function VideoReferenceChip({
+  reference,
+  index,
+  onRemove,
+}: {
+  reference: { id: string; label: string; src: string; mediaType?: string };
+  index: number;
+  onRemove: () => void;
+}) {
+  const mediaType = reference.mediaType ?? 'image';
+  const labelPrefix =
+    mediaType === 'video'
+      ? '参考视频'
+      : mediaType === 'audio'
+        ? '参考音频'
+        : '参考图';
+  const label = reference.label || `${labelPrefix}${index + 1}`;
+  const icon =
+    mediaType === 'video' ? (
+      <Film className="h-4 w-4" aria-hidden="true" />
+    ) : mediaType === 'audio' ? (
+      <Music className="h-4 w-4" aria-hidden="true" />
+    ) : (
+      <ImageIcon className="h-4 w-4" aria-hidden="true" />
+    );
+  return (
+    <ImageCanvasReferenceSlot
+      tone={mediaType === 'audio' ? 'audio' : 'video'}
+      icon={icon}
+      imageSrc={mediaType === 'image' ? reference.src : undefined}
+      label={label}
+      ariaLabel={label}
+      title={reference.label}
+      onRemove={onRemove}
+      removeLabel={`删除${label}`}
+    />
+  );
+}
+
+function VideoOptionChoice({
+  children,
+  selected,
+  className,
+  ariaLabel,
+  disabled,
+  onClick,
+}: {
+  children: ReactNode;
+  selected: boolean;
+  className?: string;
+  ariaLabel?: string;
+  disabled?: boolean;
+  onClick?: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className={['image-canvas-editor__option-popover-choice', className]
+        .filter(Boolean)
+        .join(' ')}
+      aria-label={ariaLabel}
+      aria-pressed={selected}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+
+function ImageCanvasVideoGenerationComposerView({
+  dialog,
+  style,
+  generationReferenceButtonRef,
+  isGenerationReferenceMenuOpen,
+  setGenerateDialog,
+  setIsGenerationReferenceMenuOpen,
+  setIsPickingGenerationReferenceFromCanvas,
+  renderEditorPortal,
+  buildPortalMenuStyle,
+  onRequestUpload,
+  onSubmit,
+}: {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  generationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  isGenerationReferenceMenuOpen: boolean;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setIsGenerationReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPickingGenerationReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  renderEditorPortal: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onRequestUpload: (target: UploadTarget) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+}) {
+  const [openPanel, setOpenPanel] = useState<'params' | 'model' | null>(null);
+  const paramsButtonRef = useRef<HTMLButtonElement | null>(null);
+  const modelButtonRef = useRef<HTMLButtonElement | null>(null);
+  const normalizeVideoDuration = (value: number) =>
+    Math.min(15, Math.max(4, Math.round(value)));
+  const resolution = dialog.videoResolution ?? '480p';
+  const durationSeconds = normalizeVideoDuration(
+    dialog.videoDurationSeconds ?? DEFAULT_VIDEO_DURATION_SECONDS,
+  );
+  const soundMode = dialog.videoSound ?? DEFAULT_VIDEO_SOUND;
+  const aspectRatio = dialog.videoAspectRatio ?? DEFAULT_VIDEO_ASPECT_RATIO;
+  const currentModel =
+    EDITOR_VIDEO_MODEL_OPTIONS.find(
+      (item) => item.value === dialog.videoModel,
+    ) ?? EDITOR_VIDEO_MODEL_OPTIONS[0];
+  const supportsReferences = isSeedanceVideoModel(currentModel.value);
+  const price = calculateEditorVideoPrice(
+    currentModel.value,
+    resolution,
+    durationSeconds,
+  );
+  const isGenerating = dialog.status === 'generating';
+  const closeVideoFloatingPanels = useCallback(() => {
+    setOpenPanel(null);
+    setIsGenerationReferenceMenuOpen(false);
+  }, [setIsGenerationReferenceMenuOpen]);
+
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: openPanel !== null || isGenerationReferenceMenuOpen,
+    boundaryRefs: [
+      paramsButtonRef,
+      modelButtonRef,
+      generationReferenceButtonRef,
+    ],
+    onDismiss: closeVideoFloatingPanels,
+  });
+
+  const updateVideoDialog = (patch: Partial<GenerateDialogState>) => {
+    setGenerateDialog((currentDialog) =>
+      currentDialog?.mode === 'video'
+        ? resizeGenerationPlaceholderToVideoSelection({
+            ...resetFailedVideoDialogStatus(currentDialog),
+            ...patch,
+          })
+        : currentDialog,
+    );
+  };
+
+  const updateVideoModel = (model: GenerateDialogState['videoModel']) => {
+    updateVideoDialog({
+      videoModel: model,
+      videoResolution:
+        model === VIDEO_MODEL_SEEDANCE_2_FAST && dialog.videoResolution === '1080p'
+          ? '720p'
+          : dialog.videoResolution,
+      ...(isSeedanceVideoModel(model) ? {} : { generationReferences: [] }),
+    });
+  };
+
+  return (
+    <>
+      <form
+        className="image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image image-canvas-editor__generation-composer--video"
+        style={style}
+        role="dialog"
+        aria-label="生成视频"
+        onPointerDown={(event) => event.stopPropagation()}
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (!isGenerating) {
+            onSubmit(dialog);
+          }
+        }}
+      >
+        {supportsReferences ? (
+          <div className="image-canvas-editor__reference-strip">
+            {(dialog.generationReferences ?? []).map((reference, index) => (
+              <VideoReferenceChip
+                key={reference.id}
+                reference={reference}
+                index={index}
+                onRemove={() =>
+                  updateVideoDialog({
+                    generationReferences: (
+                      dialog.generationReferences ?? []
+                    ).filter((item) => item.id !== reference.id),
+                  })
+                }
+              />
+            ))}
+            <ImageCanvasReferenceSlot
+              buttonRef={generationReferenceButtonRef}
+              tone="video"
+              icon={<ImageIcon className="h-4 w-4" aria-hidden="true" />}
+              label="参考"
+              ariaLabel="添加视频参考素材"
+              disabled={isGenerating}
+              isAdd
+              onClick={() => setIsGenerationReferenceMenuOpen((open) => !open)}
+            />
+          </div>
+        ) : null}
+        <PlatformTextField
+          variant="textarea"
+          aria-label="视频描述"
+          value={dialog.prompt}
+          disabled={isGenerating}
+          placeholder="你希望生成什么视频？"
+          size="sm"
+          density="compact"
+          className="image-canvas-editor__generation-prompt"
+          onChange={(event) =>
+            updateVideoDialog({ prompt: event.target.value })
+          }
+        />
+        <div className="image-canvas-editor__generation-composer-footer">
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions">
+            <PlatformInlineOptionButton
+              ref={paramsButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+              aria-label={`视频参数 ${aspectRatio} · ${durationSeconds}秒 · ${resolution}`}
+              aria-expanded={openPanel === 'params'}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() =>
+                setOpenPanel((currentPanel) =>
+                  currentPanel === 'params' ? null : 'params',
+                )
+              }
+            >
+              {aspectRatio} · {durationSeconds}秒 · {resolution} ·{' '}
+              {soundMode === 'off' ? '静音' : '有声'}
+            </PlatformInlineOptionButton>
+            {openPanel === 'params'
+              ? renderEditorPortal(
+                  <PlatformFloatingMenu
+                    className="image-canvas-editor__option-popover image-canvas-editor__portal-menu"
+                    label="视频参数选项"
+                    placement="top-start"
+                    style={buildPortalMenuStyle(
+                      paramsButtonRef.current,
+                      'above',
+                    )}
+                    onPointerDown={(event) => event.stopPropagation()}
+                  >
+                    <div className="image-canvas-editor__option-popover-sections">
+                      <section className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          比例
+                        </span>
+                        <div className="image-canvas-editor__option-popover-items">
+                          {EDITOR_VIDEO_ASPECT_RATIO_OPTIONS.map((option) => (
+                            <VideoOptionChoice
+                              key={option}
+                              selected={aspectRatio === option}
+                              disabled={isGenerating}
+                              ariaLabel={`比例 ${option}`}
+                              onClick={() =>
+                                updateVideoDialog({
+                                  videoAspectRatio: option,
+                                })
+                              }
+                            >
+                              {option}
+                            </VideoOptionChoice>
+                          ))}
+                        </div>
+                      </section>
+                      <section className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          时长
+                        </span>
+                        <div className="image-canvas-editor__video-duration-slider">
+                          <input
+                            type="range"
+                            min={4}
+                            max={15}
+                            step={1}
+                            value={durationSeconds}
+                            disabled={isGenerating}
+                            aria-label="视频时长"
+                            onChange={(event) =>
+                              updateVideoDialog({
+                                videoDurationSeconds: normalizeVideoDuration(
+                                  Number(event.target.value),
+                                ),
+                              })
+                            }
+                          />
+                          <span>{durationSeconds}秒</span>
+                        </div>
+                      </section>
+                      <section className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          清晰度
+                        </span>
+                        <div className="image-canvas-editor__option-popover-items">
+                          {EDITOR_VIDEO_RESOLUTION_OPTIONS.map((option) => {
+                            const available =
+                              currentModel.value !== VIDEO_MODEL_SEEDANCE_2_FAST ||
+                              option !== '1080p';
+                            return (
+                              <VideoOptionChoice
+                                key={option}
+                                selected={resolution === option}
+                                disabled={isGenerating || !available}
+                                ariaLabel={`清晰度 ${option}`}
+                                onClick={() =>
+                                  available
+                                    ? updateVideoDialog({
+                                        videoResolution: option,
+                                      })
+                                    : undefined
+                                }
+                              >
+                                {option}
+                              </VideoOptionChoice>
+                            );
+                          })}
+                        </div>
+                      </section>
+                      <section className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          声音
+                        </span>
+                        <div className="image-canvas-editor__video-toggle-row">
+                          <button
+                            type="button"
+                            className="image-canvas-editor__video-toggle"
+                            aria-pressed={soundMode === 'off'}
+                            disabled={isGenerating}
+                            onClick={() =>
+                              updateVideoDialog({
+                                videoSound:
+                                  soundMode === 'off' ? 'on' : 'off',
+                              })
+                            }
+                          >
+                            <span aria-hidden="true" />
+                            <strong>静音</strong>
+                          </button>
+                        </div>
+                      </section>
+                    </div>
+                  </PlatformFloatingMenu>,
+                )
+              : null}
+          </div>
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--model">
+            <PlatformInlineOptionButton
+              ref={modelButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--model"
+              aria-label={`模型 ${currentModel.label}`}
+              aria-expanded={openPanel === 'model'}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() =>
+                setOpenPanel((currentPanel) =>
+                  currentPanel === 'model' ? null : 'model',
+                )
+              }
+            >
+              <span className="image-canvas-editor__model-trigger-label">
+                <span
+                  className="image-canvas-editor__model-icon"
+                  aria-hidden="true"
+                >
+                  <Cpu />
+                </span>
+                <span>{currentModel.label}</span>
+              </span>
+            </PlatformInlineOptionButton>
+            {openPanel === 'model'
+              ? renderEditorPortal(
+                  <PlatformFloatingMenu
+                    className="image-canvas-editor__option-popover image-canvas-editor__option-popover--model image-canvas-editor__portal-menu"
+                    label="视频模型选项"
+                    placement="top-start"
+                    style={buildPortalMenuStyle(
+                      modelButtonRef.current,
+                      'above',
+                    )}
+                    onPointerDown={(event) => event.stopPropagation()}
+                  >
+                    <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--model">
+                      {EDITOR_VIDEO_MODEL_OPTIONS.map((option) => {
+                        const checked = currentModel.value === option.value;
+                        return (
+                          <VideoOptionChoice
+                            key={option.value}
+                            selected={checked}
+                            disabled={isGenerating}
+                            className="image-canvas-editor__option-popover-choice--model"
+                            ariaLabel={option.label}
+                            onClick={() => updateVideoModel(option.value)}
+                          >
+                            <span
+                              className="image-canvas-editor__model-icon"
+                              aria-hidden="true"
+                            >
+                              <Cpu />
+                            </span>
+                            <span>{option.label}</span>
+                            <Check
+                              className="image-canvas-editor__option-selected-check"
+                              data-visible={checked}
+                              aria-hidden="true"
+                            />
+                          </VideoOptionChoice>
+                        );
+                      })}
+                    </div>
+                  </PlatformFloatingMenu>,
+                )
+              : null}
+          </div>
+          <PlatformActionButton
+            type="submit"
+            tone="secondary"
+            size="xs"
+            shape="pill"
+            className="image-canvas-editor__generation-submit"
+            disabled={isGenerating}
+            aria-label="生成视频"
+          >
+            {isGenerating ? (
+              '生成中'
+            ) : (
+              <>
+                <span>生成</span>
+                <span className="image-canvas-editor__mud-point-inline">
+                  {price}泥点
+                </span>
+              </>
+            )}
+          </PlatformActionButton>
+        </div>
+      </form>
+      {isGenerationReferenceMenuOpen && supportsReferences
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu"
+              label="参考素材来源"
+              placement="top-start"
+              style={buildPortalMenuStyle(
+                generationReferenceButtonRef.current,
+                'above',
+              )}
+            >
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen(false);
+                  setIsPickingGenerationReferenceFromCanvas(true);
+                }}
+              >
+                从画布中选择
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen(false);
+                  setIsPickingGenerationReferenceFromCanvas(false);
+                  onRequestUpload('video-reference-image');
+                }}
+              >
+                上传图片
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen(false);
+                  setIsPickingGenerationReferenceFromCanvas(false);
+                  onRequestUpload('video-reference-video');
+                }}
+              >
+                上传视频
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen(false);
+                  setIsPickingGenerationReferenceFromCanvas(false);
+                  onRequestUpload('video-reference-audio');
+                }}
+              >
+                上传音频
+              </PlatformFloatingMenuItem>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+}
+
+function normalizeSoundDuration(value: number | null | undefined) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_SOUND_EFFECT_DURATION_SECONDS;
+  }
+  return Math.min(10, Math.max(2, Math.round(value)));
+}
+
+function resetFailedAudioDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function ImageCanvasAudioGenerationComposerView({
+  dialog,
+  style,
+  setGenerateDialog,
+  renderEditorPortal,
+  buildPortalMenuStyle,
+  onSubmit,
+}: {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  renderEditorPortal: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onSubmit: (dialog: GenerateDialogState) => void;
+}) {
+  const [isSoundOptionsOpen, setIsSoundOptionsOpen] = useState(false);
+  const soundOptionsButtonRef = useRef<HTMLButtonElement | null>(null);
+  const soundModelButtonRef = useRef<HTMLButtonElement | null>(null);
+  const isSoundEffect = dialog.mode === 'audio-sound-effect';
+  const isGenerating = dialog.status === 'generating';
+  const soundModel = dialog.soundModel ?? DEFAULT_SOUND_EFFECT_MODEL;
+  const currentSoundModel =
+    EDITOR_SOUND_EFFECT_MODEL_OPTIONS.find(
+      (option) => option.value === soundModel,
+    ) ?? EDITOR_SOUND_EFFECT_MODEL_OPTIONS[0];
+  const soundDuration = normalizeSoundDuration(dialog.soundDurationSeconds);
+  const soundOptionLabel = `${soundDuration}秒`;
+  const dialogLabel = isSoundEffect ? '生成游戏音效' : '生成游戏背景音乐';
+  const fixedModelLabel = isSoundEffect ? currentSoundModel.label : 'Suno';
+  const fixedModelAriaLabel = isSoundEffect
+    ? `音效模型 ${fixedModelLabel}`
+    : `背景音乐模型 ${fixedModelLabel}`;
+  const cost = isSoundEffect
+    ? calculateEditorSoundEffectPrice(soundModel)
+    : calculateEditorBackgroundMusicPrice(DEFAULT_BACKGROUND_MUSIC_MODEL);
+
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isSoundOptionsOpen,
+    boundaryRefs: [soundOptionsButtonRef],
+    onDismiss: () => setIsSoundOptionsOpen(false),
+  });
+
+  const updateAudioDialog = (patch: Partial<GenerateDialogState>) => {
+    setGenerateDialog((currentDialog) =>
+      currentDialog?.mode === dialog.mode
+        ? {
+            ...resetFailedAudioDialogStatus(currentDialog),
+            ...patch,
+          }
+        : currentDialog,
+    );
+  };
+
+  const updateSoundDuration = (durationSeconds: number) => {
+    updateAudioDialog({ soundDurationSeconds: normalizeSoundDuration(durationSeconds) });
+  };
+
+  return (
+    <form
+      className="image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image image-canvas-editor__generation-composer--audio"
+      style={style}
+      role="dialog"
+      aria-label={dialogLabel}
+      onPointerDown={(event) => event.stopPropagation()}
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (!isGenerating) {
+          onSubmit(dialog);
+        }
+      }}
+    >
+      <PlatformTextField
+        variant="textarea"
+        aria-label={isSoundEffect ? 'prompt' : 'gpt_description_prompt'}
+        value={dialog.prompt}
+        disabled={isGenerating}
+        placeholder={
+          isSoundEffect
+            ? '描述需要生成的游戏音效'
+            : '描述需要生成的游戏背景音乐'
+        }
+        size="sm"
+        density="compact"
+        className="image-canvas-editor__generation-prompt"
+        onChange={(event) => updateAudioDialog({ prompt: event.target.value })}
+      />
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+      <div className="image-canvas-editor__generation-composer-footer">
+        {isSoundEffect ? (
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions">
+            <PlatformInlineOptionButton
+              ref={soundOptionsButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+              aria-label={`音效时长 ${soundOptionLabel}`}
+              aria-expanded={isSoundOptionsOpen}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() => setIsSoundOptionsOpen((isOpen) => !isOpen)}
+            >
+              {soundOptionLabel}
+            </PlatformInlineOptionButton>
+            {isSoundOptionsOpen
+              ? renderEditorPortal(
+                  <PlatformFloatingMenu
+                    className="image-canvas-editor__option-popover image-canvas-editor__option-popover--audio-options image-canvas-editor__portal-menu"
+                    label="音效时长选项"
+                    placement="top-start"
+                    style={buildPortalMenuStyle(
+                      soundOptionsButtonRef.current,
+                      'above',
+                    )}
+                  >
+                    <div className="image-canvas-editor__option-popover-items image-canvas-editor__audio-type-options">
+                      {SOUND_EFFECT_DURATION_OPTIONS.map((option) => (
+                        <VideoOptionChoice
+                          key={option}
+                          selected={soundDuration === option}
+                          disabled={isGenerating}
+                          ariaLabel={`时长 ${option}秒`}
+                          onClick={() => updateSoundDuration(option)}
+                        >
+                          {option}秒
+                        </VideoOptionChoice>
+                      ))}
+                    </div>
+                  </PlatformFloatingMenu>,
+                )
+              : null}
+          </div>
+        ) : null}
+        <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--model image-canvas-editor__readonly-generation-option">
+          <PlatformInlineOptionButton
+            ref={soundModelButtonRef}
+            className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--model"
+            aria-label={fixedModelAriaLabel}
+            disabled
+          >
+            <span className="image-canvas-editor__model-trigger-label">
+              <span
+                className="image-canvas-editor__model-icon"
+                aria-hidden="true"
+              >
+                <Music />
+              </span>
+              <span>{fixedModelLabel}</span>
+            </span>
+          </PlatformInlineOptionButton>
+        </div>
+        <PlatformActionButton
+          type="submit"
+          tone="secondary"
+          size="xs"
+          shape="pill"
+          className="image-canvas-editor__generation-submit"
+          disabled={isGenerating}
+          aria-label={dialogLabel}
+        >
+          {isGenerating ? (
+            '生成中'
+          ) : (
+            <>
+              <span>生成</span>
+              <span className="image-canvas-editor__mud-point-inline">
+                {cost}泥点
+              </span>
+            </>
+          )}
+        </PlatformActionButton>
+      </div>
+    </form>
+  );
+}
+
+export function ImageCanvasGenerationComposerView({
+  specToolWrapRef,
+  publicationReferenceButtonRef,
+  characterSpecButtonRef,
+  characterReferenceButtonRef,
+  generationReferenceButtonRef,
+  iconSpecButtonRef,
+  isSpecMenuOpen,
+  isGenerationReferenceMenuOpen,
+  isPublicationReferenceMenuOpen,
+  isCharacterSpecMenuOpen,
+  isCharacterReferenceMenuOpen,
+  isIconSpecMenuOpen,
+  isUiDesignSpecMenuOpen,
+  isPickingGenerationReferenceFromCanvas,
+  isPickingQuickEditReferenceFromCanvas,
+  isPickingPublicationReferenceFromCanvas,
+  isPickingCharacterSpecFromCanvas,
+  isPickingCharacterReferenceFromCanvas,
+  isPickingIconSpecFromCanvas,
+  isPickingUiDesignSpecFromCanvas,
+  generateDialog,
+  generationComposerStyle,
+  iconComposerStyle,
+  quickEditPanel,
+  quickEditSourceLayer,
+  quickEditPanelStyle,
+  cropExpandPanel,
+  cropExpandSourceLayer,
+  cropExpandPanelStyle,
+  characterAnimationPanel,
+  characterAnimationSourceLayer,
+  characterAnimationPanelStyle,
+  characterAnimationPrice,
+  setGenerateDialog,
+  setQuickEditPanel,
+  setCropExpandPanel,
+  setCharacterAnimationPanel,
+  setIsGenerationReferenceMenuOpen,
+  setIsPublicationReferenceMenuOpen,
+  setIsCharacterSpecMenuOpen,
+  setIsCharacterReferenceMenuOpen,
+  setIsIconSpecMenuOpen,
+  setIsUiDesignSpecMenuOpen,
+  setIsPickingGenerationReferenceFromCanvas,
+  setIsPickingQuickEditReferenceFromCanvas,
+  setIsPickingPublicationReferenceFromCanvas,
+  setIsPickingCharacterSpecFromCanvas,
+  setIsPickingCharacterReferenceFromCanvas,
+  setIsPickingIconSpecFromCanvas,
+  setIsPickingUiDesignSpecFromCanvas,
+  onOpenSpecDialog,
+  onRequestUpload,
+  onSubmitImageGeneration,
+  onSubmitIconSpritesheetGeneration,
+  onSubmitQuickEdit,
+  onSubmitCropExpand,
+  onSubmitCharacterAnimation,
+  onUpdateSpecFormValue,
+  onUpdateIconDescriptionText,
+  onUpdateCharacterAnimationDuration,
+  onRememberImageModel,
+  onSpecMenuPointerEnter,
+  onSpecMenuPointerLeave,
+}: ImageCanvasGenerationComposerViewProps) {
+  return (
+    <>
+      {isSpecMenuOpen
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu"
+              label="生成规范类型"
+              placement="top-start"
+              style={buildPortalMenuStyle(specToolWrapRef.current, 'above')}
+              onPointerEnter={onSpecMenuPointerEnter}
+              onPointerLeave={onSpecMenuPointerLeave}
+              onFocus={onSpecMenuPointerEnter}
+              onBlur={onSpecMenuPointerLeave}
+            >
+              {(['character', 'ui', 'custom'] as const).map((specType) => (
+                <PlatformFloatingMenuItem
+                  key={specType}
+                  className="image-canvas-editor__spec-menu-item"
+                  onClick={() => onOpenSpecDialog(specType)}
+                >
+                  {SPEC_TYPE_LABEL[specType]}
+                </PlatformFloatingMenuItem>
+              ))}
+            </PlatformFloatingMenu>,
+          )
+        : null}
+
+      {generateDialog?.mode === 'generate' &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasBasicGenerationComposerView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          setGenerateDialog={setGenerateDialog}
+          generationReferenceButtonRef={generationReferenceButtonRef}
+          isGenerationReferenceMenuOpen={isGenerationReferenceMenuOpen}
+          setIsGenerationReferenceMenuOpen={setIsGenerationReferenceMenuOpen}
+          setIsPickingGenerationReferenceFromCanvas={
+            setIsPickingGenerationReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onRequestUpload={onRequestUpload}
+          onToggleReferenceMenu={() =>
+            setIsGenerationReferenceMenuOpen((open) => !open)
+          }
+          onRememberImageModel={onRememberImageModel}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'spec' &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasSpecGenerationPanelView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          isGenerationReferenceMenuOpen={isGenerationReferenceMenuOpen}
+          generationReferenceButtonRef={generationReferenceButtonRef}
+          setIsGenerationReferenceMenuOpen={setIsGenerationReferenceMenuOpen}
+          setIsPickingGenerationReferenceFromCanvas={
+            setIsPickingGenerationReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          setGenerateDialog={setGenerateDialog}
+          onOpenSpecDialog={onOpenSpecDialog}
+          onUpdateSpecFormValue={onUpdateSpecFormValue}
+          onRequestUpload={onRequestUpload}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'publication' &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasPublicationMaterialsDemoPanelView
+          dialog={generateDialog}
+          workflow={getPublicationMaterialsWorkflow(
+            generateDialog.publicationWorkflowId ?? 'publication-cover-image',
+          )}
+          style={generationComposerStyle}
+          publicationReferenceButtonRef={publicationReferenceButtonRef}
+          isPublicationReferenceMenuOpen={isPublicationReferenceMenuOpen}
+          setGenerateDialog={setGenerateDialog}
+          setIsPublicationReferenceMenuOpen={
+            setIsPublicationReferenceMenuOpen
+          }
+          setIsPickingPublicationReferenceFromCanvas={
+            setIsPickingPublicationReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onRequestUpload={onRequestUpload}
+          onRememberImageModel={onRememberImageModel}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'ui-design' &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasSpecGenerationPanelView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          isGenerationReferenceMenuOpen={isUiDesignSpecMenuOpen}
+          generationReferenceButtonRef={generationReferenceButtonRef}
+          setIsGenerationReferenceMenuOpen={setIsUiDesignSpecMenuOpen}
+          setIsPickingGenerationReferenceFromCanvas={
+            setIsPickingUiDesignSpecFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          setGenerateDialog={setGenerateDialog}
+          onOpenSpecDialog={onOpenSpecDialog}
+          onUpdateSpecFormValue={onUpdateSpecFormValue}
+          onRequestUpload={onRequestUpload}
+          onRememberImageModel={onRememberImageModel}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'video' &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasVideoGenerationComposerView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          generationReferenceButtonRef={generationReferenceButtonRef}
+          isGenerationReferenceMenuOpen={isGenerationReferenceMenuOpen}
+          setGenerateDialog={setGenerateDialog}
+          setIsGenerationReferenceMenuOpen={setIsGenerationReferenceMenuOpen}
+          setIsPickingGenerationReferenceFromCanvas={
+            setIsPickingGenerationReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onRequestUpload={onRequestUpload}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {(generateDialog?.mode === 'audio-sound-effect' ||
+        generateDialog?.mode === 'audio-background-music') &&
+      generateDialog.composerOpen !== false &&
+      generationComposerStyle ? (
+        <ImageCanvasAudioGenerationComposerView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          setGenerateDialog={setGenerateDialog}
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'character' && generationComposerStyle ? (
+        <ImageCanvasCharacterGenerationComposerView
+          dialog={generateDialog}
+          style={generationComposerStyle}
+          characterSpecButtonRef={characterSpecButtonRef}
+          characterReferenceButtonRef={characterReferenceButtonRef}
+          isCharacterSpecMenuOpen={isCharacterSpecMenuOpen}
+          isCharacterReferenceMenuOpen={isCharacterReferenceMenuOpen}
+          setGenerateDialog={setGenerateDialog}
+          setIsCharacterSpecMenuOpen={setIsCharacterSpecMenuOpen}
+          setIsCharacterReferenceMenuOpen={setIsCharacterReferenceMenuOpen}
+          setIsPickingCharacterSpecFromCanvas={
+            setIsPickingCharacterSpecFromCanvas
+          }
+          setIsPickingCharacterReferenceFromCanvas={
+            setIsPickingCharacterReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onOpenSpecDialog={onOpenSpecDialog}
+          onRequestUpload={onRequestUpload}
+          onRememberImageModel={onRememberImageModel}
+          onSubmit={onSubmitImageGeneration}
+        />
+      ) : null}
+
+      {generateDialog?.mode === 'icon' &&
+      generateDialog.composerOpen !== false &&
+      iconComposerStyle ? (
+        <ImageCanvasIconSpritesheetComposerView
+          dialog={generateDialog}
+          style={iconComposerStyle}
+          iconSpecButtonRef={iconSpecButtonRef}
+          isIconSpecMenuOpen={isIconSpecMenuOpen}
+          setGenerateDialog={setGenerateDialog}
+          setIsIconSpecMenuOpen={setIsIconSpecMenuOpen}
+          setIsPickingIconSpecFromCanvas={setIsPickingIconSpecFromCanvas}
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onOpenSpecDialog={onOpenSpecDialog}
+          onRequestUpload={onRequestUpload}
+          onUpdateIconDescriptionText={onUpdateIconDescriptionText}
+          onRememberImageModel={onRememberImageModel}
+          onSubmit={onSubmitIconSpritesheetGeneration}
+        />
+      ) : null}
+
+      {isPickingCharacterSpecFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图片作为角色规范，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingCharacterReferenceFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图片作为常规参考图，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingGenerationReferenceFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图片作为参考图，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingQuickEditReferenceFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图片作为参考图，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingPublicationReferenceFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图片作为宣发素材参考图，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingIconSpecFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图标规范，按 Esc 退出
+        </div>
+      ) : null}
+      {isPickingUiDesignSpecFromCanvas ? (
+        <div className="image-canvas-editor__canvas-pick-hint">
+          请选择画布中的图标规范，按 Esc 退出
+        </div>
+      ) : null}
+
+      {quickEditPanel &&
+      (quickEditPanel.mode === 'redraw' ||
+        quickEditPanel.status !== 'generating') &&
+      quickEditSourceLayer &&
+      quickEditPanelStyle ? (
+        <ImageCanvasQuickEditPanelView
+          panel={quickEditPanel}
+          sourceLayer={quickEditSourceLayer}
+          style={quickEditPanelStyle}
+          referenceButtonRef={generationReferenceButtonRef}
+          isReferenceMenuOpen={isGenerationReferenceMenuOpen}
+          setIsReferenceMenuOpen={setIsGenerationReferenceMenuOpen}
+          setIsPickingQuickEditReferenceFromCanvas={
+            setIsPickingQuickEditReferenceFromCanvas
+          }
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+          onRequestUpload={onRequestUpload}
+          onRememberImageModel={onRememberImageModel}
+          setQuickEditPanel={setQuickEditPanel}
+          onSubmit={onSubmitQuickEdit}
+        />
+      ) : null}
+
+      {cropExpandPanel &&
+      cropExpandSourceLayer &&
+      cropExpandPanelStyle ? (
+        <ImageCanvasCropExpandPanelView
+          panel={cropExpandPanel}
+          style={cropExpandPanelStyle}
+          setCropExpandPanel={setCropExpandPanel}
+          onSubmit={onSubmitCropExpand}
+        />
+      ) : null}
+
+      {characterAnimationPanel &&
+      characterAnimationSourceLayer &&
+      characterAnimationPanelStyle ? (
+        <ImageCanvasCharacterAnimationPanelView
+          panel={characterAnimationPanel}
+          style={characterAnimationPanelStyle}
+          price={characterAnimationPrice}
+          sourceLayer={characterAnimationSourceLayer}
+          setCharacterAnimationPanel={setCharacterAnimationPanel}
+          onUpdateDuration={onUpdateCharacterAnimationDuration}
+          onSubmit={onSubmitCharacterAnimation}
+        />
+      ) : null}
+
+      <ImageCanvasEditGenerationModalView
+        dialog={generateDialog}
+        setGenerateDialog={setGenerateDialog}
+        onSubmit={onSubmitImageGeneration}
+      />
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
new file mode 100644
index 000000000..20f4757e4
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts
@@ -0,0 +1,751 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasLayer,
+  CharacterAnimationPanelState,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import {
+  appendCharacterReference,
+  appendGenerationReference,
+  assignCharacterSpecReference,
+  assignIconSpecReference,
+  assignUiDesignSpecReference,
+  closeGenerateComposerDialog,
+  createAudioRedrawGenerationDialogDraft,
+  createBackgroundMusicGenerationDialogDraft,
+  createCharacterAnimationGenerationDialogDraft,
+  createCharacterAnimationPanelDraft,
+  createCharacterGenerationDialogDraft,
+  createEditDialogDraft,
+  createGenerateDialogDraft,
+  createIconGenerationDialogDraft,
+  createPublicationGenerationDialogDraft,
+  createQuickEditPanelDraft,
+  createSoundEffectGenerationDialogDraft,
+  createSpecDialogDraft,
+  createUiDesignGenerationDialogDraft,
+  createVideoGenerationDialogDraft,
+  formatIconDescriptionsText,
+  hideGeneratedLayerComposerAfterBlur,
+  parseIconDescriptionsText,
+  updateCharacterAnimationDurationPanel,
+  updateIconDescriptionsTextInDialog,
+  updateSpecFormDialogValue,
+} from './ImageCanvasGenerationDialogModel';
+import {
+  IMAGE_MODEL_NANOBANANA2,
+} from './ImageCanvasGenerationModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '源图',
+    src: 'data:image/png;base64,source',
+    x: 120,
+    y: 140,
+    width: 320,
+    height: 240,
+    originalWidth: 1024,
+    originalHeight: 768,
+    zIndex: 2,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasGenerationDialogModel', () => {
+  it('creates centered drafts for image and spec generation dialogs', () => {
+    const canvasSize = { width: 1000, height: 800 };
+    const viewport = { x: 100, y: 40, scale: 2 };
+
+    expect(createGenerateDialogDraft({ canvasSize, viewport })).toMatchObject({
+      mode: 'generate',
+      status: 'idle',
+      composerOpen: true,
+      placeholder: {
+        x: -312,
+        y: -332,
+        width: 1024,
+        height: 1024,
+        originalWidth: 1024,
+        originalHeight: 1024,
+      },
+    });
+    expect(
+      createSpecDialogDraft({ canvasSize, viewport, specType: 'icon' }),
+    ).toMatchObject({
+      mode: 'spec',
+      specType: 'icon',
+      specValues: {
+        playSetting: '休闲小游戏',
+        artStyle: '清爽卡通',
+      },
+      placeholder: {
+        x: -824,
+        y: -396,
+        width: 2048,
+        height: 1152,
+        originalWidth: 2048,
+        originalHeight: 1152,
+      },
+    });
+  });
+
+  it('creates publication material drafts with the workflow output size', () => {
+    const canvasSize = { width: 960, height: 720 };
+    const viewport = { x: 0, y: 0, scale: 1 };
+
+    expect(
+      createPublicationGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        workflowId: 'publication-promo-poster',
+      }),
+    ).toMatchObject({
+      mode: 'publication',
+      publicationWorkflowId: 'publication-promo-poster',
+      placeholder: {
+        x: -160,
+        y: 0,
+        width: 1280,
+        height: 720,
+        originalWidth: 1280,
+        originalHeight: 720,
+      },
+    });
+  });
+
+  it('creates character and icon generation drafts with model dimensions', () => {
+    const canvasSize = { width: 960, height: 720 };
+    const viewport = { x: 0, y: 0, scale: 1 };
+
+    expect(
+      createCharacterGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: 'gpt-image-2',
+      }),
+    ).toMatchObject({
+      mode: 'character',
+      imageModel: 'gpt-image-2',
+      aspectRatio: '1:1',
+      imageSize: '1K',
+      characterSpecReference: null,
+      characterReferences: [],
+      placeholder: {
+        x: -32,
+        y: -152,
+        width: 1024,
+        height: 1024,
+      },
+    });
+    expect(
+      createIconGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: 'unknown-model',
+      }),
+    ).toMatchObject({
+      mode: 'icon',
+      imageModel: 'unknown-model',
+      aspectRatio: '1:1',
+      imageSize: '1K',
+      prompt: '返回按钮\n设置按钮\n下一关按钮\n提示按钮\n原图按钮\n冻结按钮',
+      iconSpecReference: null,
+      iconDescriptions: [
+        '返回按钮',
+        '设置按钮',
+        '下一关按钮',
+        '提示按钮',
+        '原图按钮',
+        '冻结按钮',
+      ],
+      placeholder: {
+        x: -32,
+        y: -152,
+        width: 1024,
+        height: 1024,
+      },
+    });
+  });
+
+  it('creates video and UI design drafts restored from the original generation entry work', () => {
+    const canvasSize = { width: 960, height: 720 };
+    const viewport = { x: 0, y: 0, scale: 1 };
+
+    expect(createVideoGenerationDialogDraft({ canvasSize, viewport }))
+      .toMatchObject({
+        mode: 'video',
+        status: 'idle',
+        composerOpen: true,
+        generationReferences: [],
+        videoModel: 'seedance2.0-fast',
+        videoAspectRatio: '16:9',
+        videoResolution: '480p',
+        videoDurationSeconds: 4,
+        videoMode: 'std',
+        videoSound: 'on',
+        videoWebSearchEnabled: true,
+        placeholder: {
+          x: 53,
+          y: 120,
+          width: 854,
+          height: 480,
+          originalWidth: 854,
+          originalHeight: 480,
+        },
+      });
+    expect(
+      createUiDesignGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: 'gpt-image-2',
+      }),
+    ).toMatchObject({
+      mode: 'ui-design',
+      imageModel: 'gpt-image-2',
+      aspectRatio: '16:9',
+      imageSize: '1K',
+      uiDesignSpecReference: null,
+      placeholder: {
+        x: -32,
+        y: 72,
+        width: 1024,
+        height: 576,
+      },
+    });
+  });
+
+  it('creates audio generation drafts for sound effects and background music', () => {
+    const canvasSize = { width: 960, height: 720 };
+    const viewport = { x: 0, y: 0, scale: 1 };
+
+    expect(createSoundEffectGenerationDialogDraft({ canvasSize, viewport }))
+      .toMatchObject({
+        mode: 'audio-sound-effect',
+        prompt:
+          '短促清脆的游戏交互音效，带轻微闪光质感，干净收尾，适合按钮确认或收集奖励。',
+        status: 'idle',
+        composerOpen: true,
+        soundModel: 'audio1.0',
+        soundDurationSeconds: 5,
+        placeholder: {
+          x: 270,
+          y: 300,
+          width: 420,
+          height: 120,
+          originalWidth: 420,
+          originalHeight: 120,
+        },
+      });
+    expect(createBackgroundMusicGenerationDialogDraft({ canvasSize, viewport }))
+      .toMatchObject({
+        mode: 'audio-background-music',
+        prompt:
+          '适合轻松冒险游戏的循环背景音乐，温暖明亮，旋律简洁，不包含人声。',
+        status: 'idle',
+        composerOpen: true,
+        makeInstrumental: true,
+        placeholder: {
+          x: 270,
+          y: 300,
+          width: 420,
+          height: 120,
+        },
+      });
+  });
+
+  it('creates audio remodel drafts from generated audio layers without references', () => {
+    const soundLayer = createLayer({
+      id: 'layer-sfx',
+      title: '游戏音效',
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+      prompt: '金币收集音',
+      generationInputs: {
+        fields: [
+          { title: 'prompt', value: '金币收集音' },
+          { title: 'model', value: 'audio1.0' },
+          { title: 'duration', value: '7秒' },
+        ],
+        references: [],
+      },
+    });
+    const musicLayer = createLayer({
+      id: 'layer-music',
+      title: '游戏背景音乐',
+      mediaType: 'audio',
+      assetKind: 'background-music',
+      prompt: '',
+      generationInputs: {
+        fields: [{ title: 'gpt_description_prompt', value: '地牢循环音乐' }],
+        references: [],
+      },
+    });
+
+    expect(createAudioRedrawGenerationDialogDraft(soundLayer)).toMatchObject({
+      mode: 'audio-sound-effect',
+      sourceLayerId: 'layer-sfx',
+      prompt: '金币收集音',
+      soundModel: 'audio1.0',
+      soundDurationSeconds: 7,
+      composerOpen: true,
+      placeholder: {
+        x: 472,
+        y: 140,
+        width: 420,
+        height: 120,
+      },
+    });
+    expect(createAudioRedrawGenerationDialogDraft(musicLayer)).toMatchObject({
+      mode: 'audio-background-music',
+      sourceLayerId: 'layer-music',
+      prompt: '地牢循环音乐',
+      makeInstrumental: true,
+      composerOpen: true,
+      placeholder: {
+        x: 472,
+        y: 140,
+        width: 420,
+        height: 120,
+      },
+    });
+    expect(createAudioRedrawGenerationDialogDraft(createLayer())).toBeNull();
+  });
+
+  it('uses audio prompt templates when remodeling old audio layers without prompts', () => {
+    expect(
+      createAudioRedrawGenerationDialogDraft(
+        createLayer({
+          mediaType: 'audio',
+          assetKind: 'sound-effect',
+          prompt: '',
+          generationInputs: { fields: [], references: [] },
+        }),
+      ),
+    ).toMatchObject({
+      mode: 'audio-sound-effect',
+      prompt:
+        '短促清脆的游戏交互音效，带轻微闪光质感，干净收尾，适合按钮确认或收集奖励。',
+    });
+    expect(
+      createAudioRedrawGenerationDialogDraft(
+        createLayer({
+          mediaType: 'audio',
+          assetKind: 'background-music',
+          title: '游戏背景音乐',
+          prompt: '',
+          generationInputs: { fields: [], references: [] },
+        }),
+      ),
+    ).toMatchObject({
+      mode: 'audio-background-music',
+      prompt: '适合轻松冒险游戏的循环背景音乐，温暖明亮，旋律简洁，不包含人声。',
+    });
+  });
+
+  it('creates edit, quick-edit, and character animation panel drafts', () => {
+    const sourceLayer = createLayer({
+      prompt: '原图提示',
+      model: 'gpt-image-2',
+      assetKind: 'character',
+    });
+
+    expect(createEditDialogDraft(sourceLayer)).toEqual({
+      mode: 'edit',
+      prompt: '原图提示，在保持主体结构的基础上优化画面细节',
+      status: 'idle',
+      composerOpen: true,
+      sourceLayerId: 'layer-source',
+    });
+    expect(createQuickEditPanelDraft(sourceLayer)).toEqual({
+      mode: 'quick-edit',
+      sourceLayerId: 'layer-source',
+      prompt: '',
+      size: '1024x768',
+      aspectRatio: '4:3',
+      imageSize: '1K',
+      model: 'gpt-image-2',
+      quickEditReferences: [],
+      status: 'idle',
+    });
+    expect(createCharacterAnimationPanelDraft(sourceLayer)).toEqual({
+      sourceLayerId: 'layer-source',
+      promptText: '',
+      resolution: '480p',
+      ratio: 'same',
+      frameCount: 32,
+      durationSeconds: 4,
+      status: 'idle',
+    });
+    expect(createCharacterAnimationPanelDraft(createLayer())).toBeNull();
+  });
+
+  it('normalizes legacy nanobanana model aliases in quick edit drafts', () => {
+    expect(
+      createQuickEditPanelDraft(
+        createLayer({
+          model: 'nano-banana',
+        }),
+      ).model,
+    ).toBe(IMAGE_MODEL_NANOBANANA2);
+    expect(
+      createQuickEditPanelDraft(
+        createLayer({
+          model: 'nanobanana2',
+        }),
+      ).model,
+    ).toBe(IMAGE_MODEL_NANOBANANA2);
+  });
+
+  it('creates character animation generation dialog drafts for character layers', () => {
+    const canvasSize = { width: 960, height: 720 };
+    const viewport = { x: 0, y: 0, scale: 1 };
+    const characterLayer = createLayer({
+      id: 'layer-character',
+      assetKind: 'character',
+    });
+
+    expect(
+      createCharacterAnimationGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        layer: characterLayer,
+      }),
+    ).toMatchObject({
+      mode: 'character-animation',
+      sourceLayerId: 'layer-character',
+      status: 'idle',
+      composerOpen: true,
+      characterAnimationResolution: '480p',
+      characterAnimationRatio: 'same',
+      characterAnimationFrameCount: 32,
+      characterAnimationDurationSeconds: 4,
+      placeholder: {
+        x: 270,
+        y: 150,
+        width: 420,
+        height: 420,
+        originalWidth: 1024,
+        originalHeight: 1024,
+      },
+    });
+    expect(
+      createCharacterAnimationGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        layer: createLayer(),
+      }),
+    ).toBeNull();
+  });
+
+  it('resets failed character and icon dialogs when picking references', () => {
+    const characterDialog: GenerateDialogState = {
+      mode: 'character',
+      prompt: '',
+      status: 'failed',
+      errorMessage: '请选择角色规范',
+      characterReferences: [],
+    };
+    const sourceLayer = createLayer({ title: '参考图' });
+
+    expect(assignCharacterSpecReference(characterDialog, sourceLayer)).toEqual(
+      expect.objectContaining({
+        status: 'idle',
+        errorMessage: undefined,
+        composerOpen: true,
+        characterSpecReference: expect.objectContaining({
+          id: 'canvas-layer-source',
+          label: '参考图',
+          src: 'data:image/png;base64,source',
+          resourceId: 'resource-source',
+        }),
+      }),
+    );
+    expect(
+      appendCharacterReference(characterDialog, sourceLayer),
+    ).toMatchObject({
+      status: 'idle',
+      errorMessage: undefined,
+      characterReferences: [{ label: '参考图' }],
+    });
+
+    const iconDialog: GenerateDialogState = {
+      mode: 'icon',
+      prompt: '',
+      status: 'failed',
+      errorMessage: '请选择图标规范',
+    };
+    expect(
+      assignIconSpecReference(
+        iconDialog,
+        createLayer({ assetKind: 'icon-spec' }),
+      ),
+    ).toMatchObject({
+      status: 'idle',
+      errorMessage: undefined,
+      iconSpecReference: { id: 'canvas-layer-source' },
+    });
+    expect(assignIconSpecReference(iconDialog, sourceLayer)).toBe(iconDialog);
+    expect(
+      assignIconSpecReference(
+        iconDialog,
+        createLayer({
+          title: '旧UI素材规范',
+          assetKind: 'spec',
+          generationInputs: {
+            fields: [
+              {
+                title: '玩法设定',
+                value: '生成一张完整游戏UI规范汇总设定展板',
+              },
+            ],
+            references: [],
+          },
+        }),
+      ),
+    ).toMatchObject({
+      status: 'idle',
+      errorMessage: undefined,
+      iconSpecReference: { label: '旧UI素材规范' },
+    });
+  });
+
+  it('routes picked canvas references to spec, image, video, and UI design fields', () => {
+    const sourceLayer = createLayer({ title: '参考图' });
+    const videoLayer = createLayer({
+      id: 'layer-video',
+      title: '动作参考',
+      src: 'https://signed.example.com/reference.mp4',
+      mediaType: 'video',
+      objectKey: 'generated-character-drafts/editor/seedance-references/video/reference.mp4',
+      assetObjectId: 'asset-object-video',
+    });
+    expect(
+      appendGenerationReference(
+        {
+          mode: 'spec',
+          prompt: '',
+          status: 'failed',
+          errorMessage: '失败',
+        },
+        sourceLayer,
+      ),
+    ).toMatchObject({
+      status: 'idle',
+      errorMessage: undefined,
+      specReference: { label: '参考图' },
+    });
+    expect(
+      appendGenerationReference(
+        {
+          mode: 'video',
+          prompt: '',
+          status: 'idle',
+          generationReferences: [],
+        },
+        sourceLayer,
+      ),
+    ).toMatchObject({
+      generationReferences: [{ label: '参考图' }],
+    });
+    expect(
+      appendGenerationReference(
+        {
+          mode: 'video',
+          prompt: '',
+          status: 'idle',
+          videoModel: 'seedance2.0-fast',
+          generationReferences: [],
+        },
+        videoLayer,
+      ),
+    ).toMatchObject({
+      generationReferences: [
+        {
+          label: '动作参考',
+          mediaType: 'video',
+          objectKey:
+            'generated-character-drafts/editor/seedance-references/video/reference.mp4',
+          assetObjectId: 'asset-object-video',
+        },
+      ],
+    });
+    const imageDialog: GenerateDialogState = {
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      generationReferences: [],
+    };
+    expect(appendGenerationReference(imageDialog, videoLayer)).toBe(imageDialog);
+    const specDialog: GenerateDialogState = {
+      mode: 'spec',
+      prompt: '',
+      status: 'idle',
+    };
+    expect(appendGenerationReference(specDialog, videoLayer)).toBe(specDialog);
+
+    const uiDialog: GenerateDialogState = {
+      mode: 'ui-design',
+      prompt: '',
+      status: 'failed',
+      errorMessage: '失败',
+    };
+    expect(assignUiDesignSpecReference(uiDialog, sourceLayer)).toBe(uiDialog);
+    expect(
+      assignUiDesignSpecReference(
+        uiDialog,
+        createLayer({ title: '图标规范', assetKind: 'icon-spec' }),
+      ),
+    ).toMatchObject({
+      status: 'idle',
+      errorMessage: undefined,
+      uiDesignSpecReference: { label: '图标规范' },
+    });
+  });
+
+  it('limits Seedance canvas-picked references by media type', () => {
+    const videoDialog: GenerateDialogState = {
+      mode: 'video',
+      prompt: '',
+      status: 'idle',
+      videoModel: 'seedance2.0',
+      generationReferences: Array.from({ length: 3 }, (_, index) => ({
+        id: `video-${index}`,
+        label: `视频${index + 1}`,
+        src: `generated-character-drafts/video-${index}.mp4`,
+        mediaType: 'video',
+      })),
+    };
+
+    expect(
+      appendGenerationReference(
+        videoDialog,
+        createLayer({
+          id: 'video-extra',
+          title: '额外视频',
+          mediaType: 'video',
+          src: 'generated-character-drafts/video-extra.mp4',
+        }),
+      ),
+    ).toMatchObject({
+      generationReferences: [
+        { label: '视频1' },
+        { label: '视频2' },
+        { label: '视频3' },
+      ],
+    });
+    expect(
+      appendGenerationReference(
+        videoDialog,
+        createLayer({
+          id: 'audio-first',
+          title: '旁白',
+          mediaType: 'audio',
+          src: 'generated-character-drafts/audio.mp3',
+        }),
+      ),
+    ).toMatchObject({
+      generationReferences: [
+        { label: '视频1' },
+        { label: '视频2' },
+        { label: '视频3' },
+        { label: '旁白', mediaType: 'audio' },
+      ],
+    });
+  });
+
+  it('updates failed spec and icon dialog fields back to idle state', () => {
+    const specDialog: GenerateDialogState = {
+      mode: 'spec',
+      prompt: '',
+      status: 'failed',
+      errorMessage: '生成失败',
+      specType: 'custom',
+      specValues: {
+        playSetting: '',
+        artStyle: '',
+        bodyRatio: '3',
+        characterView: '',
+        customPrompt: '',
+      },
+    };
+
+    expect(
+      updateSpecFormDialogValue(specDialog, 'customPrompt', '新规范'),
+    ).toEqual(
+      expect.objectContaining({
+        status: 'idle',
+        errorMessage: undefined,
+        specValues: expect.objectContaining({
+          customPrompt: '新规范',
+          bodyRatio: '3',
+        }),
+      }),
+    );
+
+    const iconDialog: GenerateDialogState = {
+      mode: 'icon',
+      prompt: '',
+      status: 'failed',
+      errorMessage: '描述错误',
+      iconDescriptions: ['旧描述'],
+    };
+    expect(updateIconDescriptionsTextInDialog(iconDialog, '剑\n盾、药水')).toEqual(
+      expect.objectContaining({
+        status: 'idle',
+        errorMessage: undefined,
+        prompt: '剑\n盾、药水',
+        iconDescriptions: ['剑', '盾', '药水'],
+      }),
+    );
+    expect(parseIconDescriptionsText('剑，盾\n药水/宝箱|钥匙')).toEqual([
+      '剑',
+      '盾',
+      '药水',
+      '宝箱',
+      '钥匙',
+    ]);
+    expect(formatIconDescriptionsText(['剑', '盾'])).toBe('剑\n盾');
+  });
+
+  it('updates character animation duration and composer visibility', () => {
+    const failedPanel: CharacterAnimationPanelState = {
+      sourceLayerId: 'layer-character',
+      promptText: '',
+      resolution: '480p',
+      ratio: 'same',
+      frameCount: 32,
+      durationSeconds: 4,
+      status: 'failed',
+      errorMessage: '失败',
+    };
+    expect(updateCharacterAnimationDurationPanel(failedPanel, '48')).toEqual({
+      ...failedPanel,
+      frameCount: 48,
+      durationSeconds: 6,
+      status: 'idle',
+      errorMessage: undefined,
+    });
+    expect(updateCharacterAnimationDurationPanel(failedPanel, '999')).toBe(
+      failedPanel,
+    );
+
+    const generateDialog: GenerateDialogState = {
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+    };
+    expect(hideGeneratedLayerComposerAfterBlur(generateDialog)).toEqual({
+      ...generateDialog,
+      composerOpen: false,
+    });
+    expect(closeGenerateComposerDialog(generateDialog)).toEqual({
+      ...generateDialog,
+      composerOpen: false,
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationDialogModel.ts b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
new file mode 100644
index 000000000..b05b7f638
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationDialogModel.ts
@@ -0,0 +1,934 @@
+import { formatImageSizeValue } from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  CharacterAnimationPanelState,
+  GenerateDialogState,
+  PublicationMaterialsWorkflowId,
+  QuickEditPanelState,
+  SpecFormValues,
+  SpecGenerationType,
+} from './ImageCanvasEditorTypes';
+import {
+  appendLimitedQuickEditReferences,
+  AUDIO_FRAME_DISPLAY_SIZE,
+  AUDIO_FRAME_ORIGINAL_SIZE,
+  CHARACTER_ANIMATION_DURATION_OPTIONS,
+  CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE,
+  CHARACTER_ANIMATION_FRAME_ORIGINAL_SIZE,
+  createCanvasLayerReference,
+  DEFAULT_ICON_DESCRIPTIONS,
+  DEFAULT_IMAGE_MODEL,
+  DEFAULT_PUBLICATION_GAME_INFO,
+  DEFAULT_SOUND_EFFECT_DURATION_SECONDS,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  DEFAULT_SPEC_FORM_VALUES,
+  DEFAULT_VIDEO_ASPECT_RATIO,
+  DEFAULT_VIDEO_DURATION_SECONDS,
+  DEFAULT_VIDEO_MODEL,
+  DEFAULT_VIDEO_SOUND,
+  DEFAULT_VIDEO_WEB_SEARCH_ENABLED,
+  EDITOR_IMAGE_DIMENSION_OPTIONS,
+  ICON_DESCRIPTION_LIMIT,
+  inferEditorImageAspectRatio,
+  inferEditorImageSizeLabel,
+  normalizeEditorImageModel,
+  PUBLICATION_FRAME_ORIGINAL_SIZE,
+  resolveEditorImageGenerationPixelSize,
+  resolveEditorVideoGenerationPixelSize,
+  SPEC_FRAME_ORIGINAL_SIZE,
+} from './ImageCanvasGenerationModel';
+
+type CanvasSize = { width: number; height: number };
+const VIDEO_REFERENCE_LIMITS = {
+  image: 9,
+  video: 3,
+  audio: 3,
+} as const;
+const DEFAULT_SOUND_EFFECT_PROMPT =
+  '短促清脆的游戏交互音效，带轻微闪光质感，干净收尾，适合按钮确认或收集奖励。';
+const DEFAULT_BACKGROUND_MUSIC_PROMPT =
+  '适合轻松冒险游戏的循环背景音乐，温暖明亮，旋律简洁，不包含人声。';
+
+function getViewportWorldCenter({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}) {
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  return {
+    x: (canvasSize.width / 2 - viewport.x) / safeScale,
+    y: (canvasSize.height / 2 - viewport.y) / safeScale,
+  };
+}
+
+function resetFailedGenerationDialog(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function resetFailedGenerationPanel(panel: QuickEditPanelState) {
+  return {
+    ...panel,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+  };
+}
+
+export function parseIconDescriptionsText(text: string): string[] {
+  return text
+    .split(/[\r\n,，、;；/|]+/u)
+    .map((description) => description.trim())
+    .filter(Boolean)
+    .slice(0, ICON_DESCRIPTION_LIMIT);
+}
+
+export function formatIconDescriptionsText(descriptions: string[]): string {
+  return descriptions.join('\n');
+}
+
+function isSeedanceVideoModel(model: string | undefined) {
+  const resolvedModel = model ?? DEFAULT_VIDEO_MODEL;
+  return resolvedModel === 'seedance2.0' || resolvedModel === 'seedance2.0-fast';
+}
+
+function getReferenceMediaType(layer: CanvasLayer) {
+  return layer.mediaType === 'video' || layer.mediaType === 'audio'
+    ? layer.mediaType
+    : 'image';
+}
+
+function isIconSpecReferenceLayer(layer: CanvasLayer) {
+  if (layer.assetKind === 'icon-spec') {
+    return true;
+  }
+  // 中文注释：历史“UI素材规范”图层以普通 spec 保存，但语义上就是图标规范，允许继续作为图标生成参考。
+  if (layer.assetKind !== 'spec') {
+    return false;
+  }
+  return (
+    layer.title.includes('图标规范') ||
+    layer.title.includes('UI素材规范') ||
+    layer.generationInputs?.fields.some(
+      (field) =>
+        field.value.includes('游戏UI规范') || field.value.includes('图标规范'),
+    ) === true
+  );
+}
+
+function appendLimitedSeedanceCanvasReference(
+  references: NonNullable<GenerateDialogState['generationReferences']>,
+  layer: CanvasLayer,
+) {
+  const mediaType = getReferenceMediaType(layer);
+  const currentCount = references.filter(
+    (reference) => (reference.mediaType ?? 'image') === mediaType,
+  ).length;
+  if (currentCount >= VIDEO_REFERENCE_LIMITS[mediaType]) {
+    return references;
+  }
+  return [...references, createCanvasLayerReference(layer)];
+}
+
+function resolveImageDimensionDefaults(imageModel: string) {
+  const normalizedImageModel = normalizeEditorImageModel(imageModel);
+  const dimensionOptions =
+    EDITOR_IMAGE_DIMENSION_OPTIONS[
+      normalizedImageModel as keyof typeof EDITOR_IMAGE_DIMENSION_OPTIONS
+    ] ?? EDITOR_IMAGE_DIMENSION_OPTIONS[DEFAULT_IMAGE_MODEL];
+  return {
+    aspectRatio: dimensionOptions.aspectRatios[0],
+    imageSize:
+      dimensionOptions.imageSizes.find((size) => size === '1K') ??
+      dimensionOptions.imageSizes[0],
+  };
+}
+
+export function createGenerateDialogDraft({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const dimensionDefaults = resolveImageDimensionDefaults(DEFAULT_IMAGE_MODEL);
+  const placeholderSize = resolveEditorImageGenerationPixelSize({
+    model: DEFAULT_IMAGE_MODEL,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+  });
+  return {
+    mode: 'generate',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    imageModel: DEFAULT_IMAGE_MODEL,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+    placeholder: {
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
+    },
+  };
+}
+
+export function createSpecDialogDraft({
+  canvasSize,
+  viewport,
+  specType,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  specType: SpecGenerationType;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  return {
+    mode: 'spec',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    specType,
+    specValues: { ...DEFAULT_SPEC_FORM_VALUES[specType] },
+    placeholder: {
+      x: worldCenter.x - SPEC_FRAME_ORIGINAL_SIZE.width / 2,
+      y: worldCenter.y - SPEC_FRAME_ORIGINAL_SIZE.height / 2,
+      width: SPEC_FRAME_ORIGINAL_SIZE.width,
+      height: SPEC_FRAME_ORIGINAL_SIZE.height,
+      originalWidth: SPEC_FRAME_ORIGINAL_SIZE.width,
+      originalHeight: SPEC_FRAME_ORIGINAL_SIZE.height,
+    },
+  };
+}
+
+export function createCharacterGenerationDialogDraft({
+  canvasSize,
+  viewport,
+  imageModel,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  imageModel: string;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const normalizedImageModel = normalizeEditorImageModel(imageModel);
+  const dimensionDefaults = resolveImageDimensionDefaults(normalizedImageModel);
+  const placeholderSize = resolveEditorImageGenerationPixelSize({
+    model: normalizedImageModel,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+  });
+  return {
+    mode: 'character',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    characterSpecReference: null,
+    characterReferences: [],
+    imageModel: normalizedImageModel,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+    placeholder: {
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
+    },
+  };
+}
+
+export function createIconGenerationDialogDraft({
+  canvasSize,
+  viewport,
+  imageModel,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  imageModel: string;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const normalizedImageModel = normalizeEditorImageModel(imageModel);
+  const dimensionDefaults = resolveImageDimensionDefaults(normalizedImageModel);
+  const placeholderSize = resolveEditorImageGenerationPixelSize({
+    model: normalizedImageModel,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+  });
+  return {
+    mode: 'icon',
+    prompt: formatIconDescriptionsText(DEFAULT_ICON_DESCRIPTIONS),
+    status: 'idle',
+    composerOpen: true,
+    iconSpecReference: null,
+    iconDescriptions: [...DEFAULT_ICON_DESCRIPTIONS],
+    imageModel: normalizedImageModel,
+    aspectRatio: dimensionDefaults.aspectRatio,
+    imageSize: dimensionDefaults.imageSize,
+    placeholder: {
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
+    },
+  };
+}
+
+export function createPublicationGenerationDialogDraft({
+  canvasSize,
+  viewport,
+  workflowId,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  workflowId: PublicationMaterialsWorkflowId;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const frameOriginalSize = PUBLICATION_FRAME_ORIGINAL_SIZE[workflowId];
+  return {
+    mode: 'publication',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    publicationWorkflowId: workflowId,
+    publicationGameInfo: { ...DEFAULT_PUBLICATION_GAME_INFO },
+    publicationReferences: [],
+    placeholder: {
+      x: worldCenter.x - frameOriginalSize.width / 2,
+      y: worldCenter.y - frameOriginalSize.height / 2,
+      width: frameOriginalSize.width,
+      height: frameOriginalSize.height,
+      originalWidth: frameOriginalSize.width,
+      originalHeight: frameOriginalSize.height,
+    },
+  };
+}
+
+export function createVideoGenerationDialogDraft({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const placeholderSize = resolveEditorVideoGenerationPixelSize({
+    aspectRatio: DEFAULT_VIDEO_ASPECT_RATIO,
+    resolution: '480p',
+  });
+  return {
+    mode: 'video',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    generationReferences: [],
+    videoModel: DEFAULT_VIDEO_MODEL,
+    videoAspectRatio: DEFAULT_VIDEO_ASPECT_RATIO,
+    videoResolution: '480p',
+    videoDurationSeconds: DEFAULT_VIDEO_DURATION_SECONDS,
+    videoMode: 'std',
+    videoSound: DEFAULT_VIDEO_SOUND,
+    videoWebSearchEnabled: DEFAULT_VIDEO_WEB_SEARCH_ENABLED,
+    placeholder: {
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
+    },
+  };
+}
+
+export function createSoundEffectGenerationDialogDraft({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  return {
+    mode: 'audio-sound-effect',
+    prompt: DEFAULT_SOUND_EFFECT_PROMPT,
+    status: 'idle',
+    composerOpen: true,
+    soundModel: DEFAULT_SOUND_EFFECT_MODEL,
+    soundDurationSeconds: DEFAULT_SOUND_EFFECT_DURATION_SECONDS,
+    placeholder: {
+      x: worldCenter.x - AUDIO_FRAME_DISPLAY_SIZE.width / 2,
+      y: worldCenter.y - AUDIO_FRAME_DISPLAY_SIZE.height / 2,
+      width: AUDIO_FRAME_DISPLAY_SIZE.width,
+      height: AUDIO_FRAME_DISPLAY_SIZE.height,
+      originalWidth: AUDIO_FRAME_ORIGINAL_SIZE.width,
+      originalHeight: AUDIO_FRAME_ORIGINAL_SIZE.height,
+    },
+  };
+}
+
+export function createBackgroundMusicGenerationDialogDraft({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  return {
+    mode: 'audio-background-music',
+    prompt: DEFAULT_BACKGROUND_MUSIC_PROMPT,
+    status: 'idle',
+    composerOpen: true,
+    makeInstrumental: true,
+    placeholder: {
+      x: worldCenter.x - AUDIO_FRAME_DISPLAY_SIZE.width / 2,
+      y: worldCenter.y - AUDIO_FRAME_DISPLAY_SIZE.height / 2,
+      width: AUDIO_FRAME_DISPLAY_SIZE.width,
+      height: AUDIO_FRAME_DISPLAY_SIZE.height,
+      originalWidth: AUDIO_FRAME_ORIGINAL_SIZE.width,
+      originalHeight: AUDIO_FRAME_ORIGINAL_SIZE.height,
+    },
+  };
+}
+
+function findGenerationInputFieldValue(
+  layer: CanvasLayer,
+  titles: string[],
+) {
+  const normalizedTitles = new Set(titles.map((title) => title.toLowerCase()));
+  return (
+    layer.generationInputs?.fields.find((field) =>
+      normalizedTitles.has(field.title.trim().toLowerCase()),
+    )?.value ?? null
+  );
+}
+
+function resolveDefaultAudioPrompt(
+  mode: Extract<
+    GenerateDialogState['mode'],
+    'audio-sound-effect' | 'audio-background-music'
+  >,
+) {
+  return mode === 'audio-background-music'
+    ? DEFAULT_BACKGROUND_MUSIC_PROMPT
+    : DEFAULT_SOUND_EFFECT_PROMPT;
+}
+
+function resolveAudioRedrawPrompt(
+  sourceLayer: CanvasLayer,
+  mode: Extract<
+    GenerateDialogState['mode'],
+    'audio-sound-effect' | 'audio-background-music'
+  >,
+) {
+  return (
+    sourceLayer.prompt?.trim() ||
+    findGenerationInputFieldValue(sourceLayer, [
+      'prompt',
+      'sound',
+      'gpt_description_prompt',
+      '生成提示词',
+      '音效提示词',
+      '背景音乐提示词',
+    ])?.trim() ||
+    sourceLayer.generationInputs?.fields[0]?.value?.trim() ||
+    resolveDefaultAudioPrompt(mode)
+  );
+}
+
+function resolveAudioRedrawMode(sourceLayer: CanvasLayer) {
+  if (sourceLayer.assetKind === 'background-music') {
+    return 'audio-background-music' as const;
+  }
+  if (sourceLayer.assetKind === 'sound-effect') {
+    return 'audio-sound-effect' as const;
+  }
+  if (sourceLayer.mediaType !== 'audio') {
+    return null;
+  }
+  return sourceLayer.title.includes('背景音乐')
+    ? ('audio-background-music' as const)
+    : ('audio-sound-effect' as const);
+}
+
+function resolveAudioRedrawSoundModel(
+  sourceLayer: CanvasLayer,
+): NonNullable<GenerateDialogState['soundModel']> {
+  const fieldValue = findGenerationInputFieldValue(sourceLayer, ['model'])
+    ?.trim();
+  // 中文注释：编辑器音效改造入口当前只暴露 Vidu audio1.0，历史快照里的其他模型统一回落到默认模型。
+  return fieldValue === DEFAULT_SOUND_EFFECT_MODEL ? 'audio1.0' : 'audio1.0';
+}
+
+function resolveAudioRedrawSoundDuration(sourceLayer: CanvasLayer) {
+  const fieldValue = findGenerationInputFieldValue(sourceLayer, ['duration']);
+  const matchedValue = fieldValue?.match(/\d+/u)?.[0];
+  const duration = matchedValue ? Number.parseInt(matchedValue, 10) : null;
+  if (!duration || !Number.isFinite(duration)) {
+    return DEFAULT_SOUND_EFFECT_DURATION_SECONDS;
+  }
+  return Math.min(10, Math.max(2, duration));
+}
+
+export function createAudioRedrawGenerationDialogDraft(
+  sourceLayer: CanvasLayer,
+): Omit<CanvasGenerationDialogState, 'id'> | null {
+  const mode = resolveAudioRedrawMode(sourceLayer);
+  if (!mode) {
+    return null;
+  }
+  const baseDraft = {
+    mode,
+    sourceLayerId: sourceLayer.id,
+    prompt: resolveAudioRedrawPrompt(sourceLayer, mode),
+    status: 'idle' as const,
+    composerOpen: true,
+    placeholder: {
+      x: sourceLayer.x + sourceLayer.width + 32,
+      y: sourceLayer.y,
+      width: AUDIO_FRAME_DISPLAY_SIZE.width,
+      height: AUDIO_FRAME_DISPLAY_SIZE.height,
+      originalWidth: AUDIO_FRAME_ORIGINAL_SIZE.width,
+      originalHeight: AUDIO_FRAME_ORIGINAL_SIZE.height,
+    },
+  };
+
+  if (mode === 'audio-background-music') {
+    return {
+      ...baseDraft,
+      makeInstrumental: true,
+    };
+  }
+
+  return {
+    ...baseDraft,
+    soundModel: resolveAudioRedrawSoundModel(sourceLayer),
+    soundDurationSeconds: resolveAudioRedrawSoundDuration(sourceLayer),
+  };
+}
+
+export function createUiDesignGenerationDialogDraft({
+  canvasSize,
+  viewport,
+  imageModel,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  imageModel: string;
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const normalizedImageModel = normalizeEditorImageModel(imageModel);
+  const dimensionDefaults = resolveImageDimensionDefaults(normalizedImageModel);
+  const placeholderSize = resolveEditorImageGenerationPixelSize({
+    model: normalizedImageModel,
+    aspectRatio: '16:9',
+    imageSize: dimensionDefaults.imageSize,
+  });
+  return {
+    mode: 'ui-design',
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    uiDesignSpecReference: null,
+    imageModel: normalizedImageModel,
+    aspectRatio: '16:9',
+    imageSize: dimensionDefaults.imageSize,
+    placeholder: {
+      x: worldCenter.x - placeholderSize.width / 2,
+      y: worldCenter.y - placeholderSize.height / 2,
+      width: placeholderSize.width,
+      height: placeholderSize.height,
+      originalWidth: placeholderSize.width,
+      originalHeight: placeholderSize.height,
+    },
+  };
+}
+
+export function createEditDialogDraft(
+  sourceLayer: CanvasLayer,
+): GenerateDialogState {
+  return {
+    mode: 'edit',
+    prompt: sourceLayer.prompt
+      ? `${sourceLayer.prompt}，在保持主体结构的基础上优化画面细节`
+      : '',
+    status: 'idle',
+    composerOpen: true,
+    sourceLayerId: sourceLayer.id,
+  };
+}
+
+export function createQuickEditPanelDraft(
+  sourceLayer: CanvasLayer,
+): QuickEditPanelState {
+  const aspectRatio = inferEditorImageAspectRatio(
+    sourceLayer.originalWidth,
+    sourceLayer.originalHeight,
+  );
+  const imageSize = inferEditorImageSizeLabel(
+    sourceLayer.originalWidth,
+    sourceLayer.originalHeight,
+  );
+  return {
+    mode: 'quick-edit',
+    sourceLayerId: sourceLayer.id,
+    prompt: '',
+    size: formatImageSizeValue(
+      sourceLayer.originalWidth,
+      sourceLayer.originalHeight,
+    ),
+    aspectRatio,
+    imageSize,
+    model: normalizeEditorImageModel(sourceLayer.model),
+    quickEditReferences: [],
+    status: 'idle',
+  };
+}
+
+export function createQuickEditGenerationDialogDraft({
+  sourceLayer,
+  prompt,
+  status = 'idle',
+  references = [],
+  model,
+  aspectRatio,
+  imageSize,
+  frame,
+}: {
+  sourceLayer: CanvasLayer;
+  prompt: string;
+  status?: CanvasGenerationDialogState['status'];
+  references?: NonNullable<QuickEditPanelState['quickEditReferences']>;
+  model?: string;
+  aspectRatio?: string;
+  imageSize?: string;
+  frame?: { width: number; height: number };
+}): Omit<CanvasGenerationDialogState, 'id'> {
+  const frameWidth = frame?.width ?? sourceLayer.width;
+  const frameHeight = frame?.height ?? sourceLayer.height;
+  return {
+    mode: 'quick-edit',
+    prompt,
+    status,
+    composerOpen: false,
+    sourceLayerId: sourceLayer.id,
+    generationReferences: references.slice(0, 8),
+    imageModel: normalizeEditorImageModel(model ?? sourceLayer.model),
+    aspectRatio,
+    imageSize,
+    placeholder: {
+      x: sourceLayer.x + sourceLayer.width + 32,
+      y: sourceLayer.y,
+      width: frameWidth,
+      height: frameHeight,
+      originalWidth: frameWidth,
+      originalHeight: frameHeight,
+    },
+  };
+}
+
+export function createRedrawPanelDraft(
+  sourceLayer: CanvasLayer,
+): QuickEditPanelState {
+  return {
+    ...createQuickEditPanelDraft(sourceLayer),
+    mode: 'redraw',
+    prompt:
+      sourceLayer.prompt?.trim() ||
+      sourceLayer.generationInputs?.fields[0]?.value?.trim() ||
+      '',
+  };
+}
+
+export function createCharacterAnimationPanelDraft(
+  layer: CanvasLayer,
+): CharacterAnimationPanelState | null {
+  if (layer.assetKind !== 'character') {
+    return null;
+  }
+  return {
+    sourceLayerId: layer.id,
+    promptText: '',
+    resolution: '480p',
+    ratio: 'same',
+    frameCount: 32,
+    durationSeconds: 4,
+    status: 'idle',
+  };
+}
+
+export function createCharacterAnimationGenerationDialogDraft({
+  canvasSize,
+  viewport,
+  layer,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  layer: CanvasLayer;
+}): Omit<CanvasGenerationDialogState, 'id'> | null {
+  if (layer.assetKind !== 'character') {
+    return null;
+  }
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  return {
+    mode: 'character-animation',
+    sourceLayerId: layer.id,
+    prompt: '',
+    status: 'idle',
+    composerOpen: true,
+    characterAnimationResolution: '480p',
+    characterAnimationRatio: 'same',
+    characterAnimationFrameCount: 32,
+    characterAnimationDurationSeconds: 4,
+    placeholder: {
+      x: worldCenter.x - CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE.width / 2,
+      y: worldCenter.y - CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE.height / 2,
+      width: CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE.width,
+      height: CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE.height,
+      originalWidth: CHARACTER_ANIMATION_FRAME_ORIGINAL_SIZE.width,
+      originalHeight: CHARACTER_ANIMATION_FRAME_ORIGINAL_SIZE.height,
+    },
+  };
+}
+
+export function assignCharacterSpecReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  return dialog?.mode === 'character' && getReferenceMediaType(layer) === 'image'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        characterSpecReference: createCanvasLayerReference(layer),
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function appendCharacterReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  return dialog?.mode === 'character' && getReferenceMediaType(layer) === 'image'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        characterReferences: [
+          ...(dialog.characterReferences ?? []),
+          createCanvasLayerReference(layer),
+        ],
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function appendGenerationReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  if (dialog?.mode === 'spec') {
+    if (getReferenceMediaType(layer) !== 'image') {
+      return dialog;
+    }
+    return {
+      ...resetFailedGenerationDialog(dialog),
+      specReference: createCanvasLayerReference(layer),
+      composerOpen: true,
+    };
+  }
+  if (dialog?.mode === 'video' && !isSeedanceVideoModel(dialog.videoModel)) {
+    return dialog;
+  }
+  if (dialog?.mode === 'generate') {
+    if (getReferenceMediaType(layer) !== 'image') {
+      return dialog;
+    }
+    return {
+      ...resetFailedGenerationDialog(dialog),
+      generationReferences: [
+        ...(dialog.generationReferences ?? []),
+        createCanvasLayerReference(layer),
+      ],
+      composerOpen: true,
+    };
+  }
+  return dialog?.mode === 'video'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        generationReferences: appendLimitedSeedanceCanvasReference(
+          dialog.generationReferences ?? [],
+          layer,
+        ),
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function appendPublicationReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  return dialog?.mode === 'publication' && getReferenceMediaType(layer) === 'image'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        publicationReferences: [
+          ...(dialog.publicationReferences ?? []),
+          createCanvasLayerReference(layer),
+        ],
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function assignIconSpecReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  if (!isIconSpecReferenceLayer(layer)) {
+    return dialog;
+  }
+  return dialog?.mode === 'icon'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        iconSpecReference: createCanvasLayerReference(layer),
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function assignUiDesignSpecReference(
+  dialog: GenerateDialogState | null,
+  layer: CanvasLayer,
+): GenerateDialogState | null {
+  if (!isIconSpecReferenceLayer(layer)) {
+    return dialog;
+  }
+  return dialog?.mode === 'ui-design'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        uiDesignSpecReference: createCanvasLayerReference(layer),
+        composerOpen: true,
+      }
+    : dialog;
+}
+
+export function updateSpecFormDialogValue(
+  dialog: GenerateDialogState | null,
+  key: keyof SpecFormValues,
+  value: string,
+): GenerateDialogState | null {
+  if (dialog?.mode !== 'spec') {
+    return dialog;
+  }
+  const specType = dialog.specType ?? 'custom';
+  return {
+    ...resetFailedGenerationDialog(dialog),
+    specValues: {
+      ...DEFAULT_SPEC_FORM_VALUES[specType],
+      ...dialog.specValues,
+      [key]: value,
+    },
+  };
+}
+
+export function updateIconDescriptionsTextInDialog(
+  dialog: GenerateDialogState | null,
+  value: string,
+): GenerateDialogState | null {
+  return dialog?.mode === 'icon'
+    ? {
+        ...resetFailedGenerationDialog(dialog),
+        prompt: value,
+        iconDescriptions: parseIconDescriptionsText(value),
+      }
+    : dialog;
+}
+
+export function appendQuickEditReference(
+  panel: QuickEditPanelState | null,
+  layer: CanvasLayer,
+): QuickEditPanelState | null {
+  if (!panel || panel.mode === 'redraw' || getReferenceMediaType(layer) !== 'image') {
+    return panel;
+  }
+  return {
+    ...resetFailedGenerationPanel(panel),
+    quickEditReferences: appendLimitedQuickEditReferences(
+      panel.quickEditReferences,
+      [createCanvasLayerReference(layer)],
+    ),
+  };
+}
+
+export function updateCharacterAnimationDurationPanel(
+  panel: CharacterAnimationPanelState | null,
+  frameCountValue: string,
+): CharacterAnimationPanelState | null {
+  const option = CHARACTER_ANIMATION_DURATION_OPTIONS.find(
+    (item) => String(item.frameCount) === frameCountValue,
+  );
+  if (!option || !panel) {
+    return panel;
+  }
+  return {
+    ...panel,
+    frameCount: option.frameCount,
+    durationSeconds: option.durationSeconds,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+  };
+}
+
+export function hideGeneratedLayerComposerAfterBlur(
+  dialog: GenerateDialogState | null,
+): GenerateDialogState | null {
+  return (dialog?.mode === 'generate' ||
+    dialog?.mode === 'spec' ||
+    dialog?.mode === 'character' ||
+    dialog?.mode === 'icon' ||
+    dialog?.mode === 'ui-design' ||
+    dialog?.mode === 'quick-edit' ||
+    dialog?.mode === 'character-animation' ||
+    dialog?.mode === 'video' ||
+    dialog?.mode === 'publication' ||
+    dialog?.mode === 'audio-sound-effect' ||
+    dialog?.mode === 'audio-background-music') &&
+    dialog.status !== 'generating'
+    ? {
+        ...dialog,
+        composerOpen: false,
+      }
+    : dialog;
+}
+
+export function closeGenerateComposerDialog(
+  dialog: GenerateDialogState | null,
+): GenerateDialogState | null {
+  return dialog?.mode === 'generate' ||
+    dialog?.mode === 'spec' ||
+    dialog?.mode === 'character' ||
+    dialog?.mode === 'icon' ||
+    dialog?.mode === 'ui-design' ||
+    dialog?.mode === 'quick-edit' ||
+    dialog?.mode === 'character-animation' ||
+    dialog?.mode === 'video' ||
+    dialog?.mode === 'publication' ||
+    dialog?.mode === 'audio-sound-effect' ||
+    dialog?.mode === 'audio-background-music'
+    ? {
+        ...dialog,
+        composerOpen: false,
+      }
+    : dialog;
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx
new file mode 100644
index 000000000..4c9f446a5
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx
@@ -0,0 +1,276 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import {
+  calculateEditorImageGenerationPrice,
+  IMAGE_MODEL_GPT_IMAGE_2,
+  IMAGE_MODEL_NANOBANANA2,
+} from './ImageCanvasGenerationModel';
+
+function ImageOptionsHarness({
+  initialDialog,
+  includeDimensions = true,
+  onRememberImageModel = vi.fn(),
+}: {
+  initialDialog: GenerateDialogState;
+  includeDimensions?: boolean;
+  onRememberImageModel?: (model: string) => void;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+
+  return dialog ? (
+    <div>
+      <ImageCanvasGenerationImageOptionsView
+        dialog={dialog}
+        setGenerateDialog={setDialog}
+        includeDimensions={includeDimensions}
+        onRememberImageModel={onRememberImageModel}
+        cost={calculateEditorImageGenerationPrice({ model: dialog.imageModel })}
+        submitLabel="生成"
+        submitAriaLabel="生成角色形象"
+      />
+      <output aria-label="当前模型">{dialog.imageModel}</output>
+      <output aria-label="当前比例">{dialog.aspectRatio}</output>
+      <output aria-label="当前尺寸">{dialog.imageSize}</output>
+      <output aria-label="当前状态">{dialog.status}</output>
+      <output aria-label="当前错误">{dialog.errorMessage ?? '-'}</output>
+      <output aria-label="当前占位">
+        {dialog.placeholder
+          ? [
+              dialog.placeholder.x,
+              dialog.placeholder.y,
+              dialog.placeholder.width,
+              dialog.placeholder.height,
+              dialog.placeholder.originalWidth,
+              dialog.placeholder.originalHeight,
+            ].join(':')
+          : '-'}
+      </output>
+    </div>
+  ) : null;
+}
+
+describe('ImageCanvasGenerationImageOptionsView', () => {
+  it('updates dimensions from a menu, keeps the menu open and marks the selection', () => {
+    render(
+      <ImageOptionsHarness
+        initialDialog={{
+          mode: 'character',
+          prompt: '',
+          status: 'failed',
+          errorMessage: '旧错误',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '1:1',
+          imageSize: '1K',
+        }}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片尺寸 1:1·1K' }),
+    );
+    const panel = screen.getByRole('menu', { name: '生成图片尺寸选项' });
+
+    fireEvent.click(within(panel).getByRole('button', { name: '16:9' }));
+    fireEvent.click(within(panel).getByRole('button', { name: '2K' }));
+
+    expect(screen.getByRole('menu', { name: '生成图片尺寸选项' })).toBeTruthy();
+    expect(
+      within(panel)
+        .getByRole('button', { name: '16:9' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+    expect(
+      within(panel)
+        .getByRole('button', { name: '2K' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+    expect(
+      screen.getByRole('button', { name: '生成图片尺寸 16:9·2K' }),
+    ).toBeTruthy();
+    expect(screen.getByLabelText('当前比例').textContent).toBe('16:9');
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('2K');
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+  });
+
+  it('closes option panels when clicking parent panel outside trigger buttons', () => {
+    render(
+      <ImageOptionsHarness
+        initialDialog={{
+          mode: 'generate',
+          prompt: '',
+          status: 'idle',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '1:1',
+          imageSize: '1K',
+        }}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片尺寸 1:1·1K' }),
+    );
+    expect(
+      screen.getByRole('menu', { name: '生成图片尺寸选项' }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByLabelText('当前模型'));
+
+    expect(
+      screen.queryByRole('menu', { name: '生成图片尺寸选项' }),
+    ).toBeNull();
+  });
+
+  it('renders model choices as one model per row and uses a check mark for selection', () => {
+    const rememberImageModel = vi.fn();
+    render(
+      <ImageOptionsHarness
+        initialDialog={{
+          mode: 'icon',
+          prompt: '',
+          status: 'idle',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '9:16',
+          imageSize: '0.5K',
+        }}
+        onRememberImageModel={rememberImageModel}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片模型 nanobanana2' }),
+    );
+    const panel = screen.getByRole('menu', { name: '生成图片模型选项' });
+
+    expect(within(panel).getByRole('button', { name: 'nanobanana2' })).toBeTruthy();
+    fireEvent.click(within(panel).getByRole('button', { name: 'gpt-image-2' }));
+
+    expect(screen.getByRole('menu', { name: '生成图片模型选项' })).toBeTruthy();
+    expect(rememberImageModel).toHaveBeenCalledWith(IMAGE_MODEL_GPT_IMAGE_2);
+    expect(screen.getByLabelText('当前模型').textContent).toBe(
+      IMAGE_MODEL_GPT_IMAGE_2,
+    );
+    expect(screen.getByLabelText('当前比例').textContent).toBe('9:16');
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('1K');
+    expect(
+      screen.getByRole('button', { name: '生成图片模型 gpt-image-2' }),
+    ).toBeTruthy();
+    expect(screen.getByRole('button', { name: '生成角色形象' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('renders option menus and shows mud point text in the submit button', () => {
+    render(
+      <ImageOptionsHarness
+        initialDialog={{
+          mode: 'generate',
+          prompt: '',
+          status: 'idle',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '1:1',
+          imageSize: '1K',
+        }}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片尺寸 1:1·1K' }),
+    );
+
+    expect(
+      screen.getByRole('menu', { name: '生成图片尺寸选项' }),
+    ).toBeTruthy();
+    const submit = screen.getByRole('button', { name: '生成角色形象' });
+    expect(submit.textContent).toBe('生成12泥点');
+  });
+
+  it('keeps fixed-card placeholders unchanged when model-only controls are shown', () => {
+    render(
+      <ImageOptionsHarness
+        includeDimensions={false}
+        initialDialog={{
+          mode: 'publication',
+          prompt: '',
+          status: 'idle',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '4:3',
+          imageSize: '1K',
+          placeholder: {
+            x: 120,
+            y: 160,
+            width: 720,
+            height: 540,
+            originalWidth: 720,
+            originalHeight: 540,
+          },
+        }}
+      />,
+    );
+
+    expect(
+      screen.queryByRole('button', { name: /生成图片尺寸/u }),
+    ).toBeNull();
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片模型 nanobanana2' }),
+    );
+    fireEvent.click(
+      within(screen.getByRole('menu', { name: '生成图片模型选项' })).getByRole(
+        'button',
+        { name: 'gpt-image-2' },
+      ),
+    );
+
+    expect(screen.getByLabelText('当前模型').textContent).toBe(
+      IMAGE_MODEL_GPT_IMAGE_2,
+    );
+    expect(screen.getByLabelText('当前比例').textContent).toBe('4:3');
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('1K');
+    expect(screen.getByLabelText('当前占位').textContent).toBe(
+      '120:160:720:540:720:540',
+    );
+  });
+
+  it('keeps the canvas placeholder centered while syncing its ratio and size selection', () => {
+    render(
+      <ImageOptionsHarness
+        initialDialog={{
+          mode: 'character',
+          prompt: '',
+          status: 'idle',
+          imageModel: IMAGE_MODEL_NANOBANANA2,
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          placeholder: {
+            x: 100,
+            y: 200,
+            width: 420,
+            height: 420,
+            originalWidth: 1024,
+            originalHeight: 1024,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片尺寸 1:1·1K' }),
+    );
+    const panel = screen.getByRole('menu', { name: '生成图片尺寸选项' });
+    fireEvent.click(within(panel).getByRole('button', { name: '16:9' }));
+    fireEvent.click(within(panel).getByRole('button', { name: '2K' }));
+
+    expect(screen.getByLabelText('当前占位').textContent).toBe(
+      '-714:-166:2048:1152:2048:1152',
+    );
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationImageOptionsView.tsx b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.tsx
new file mode 100644
index 000000000..3d7462c03
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationImageOptionsView.tsx
@@ -0,0 +1,340 @@
+import { Check, ChevronDown, Cpu } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformFloatingMenu } from '../common/PlatformFloatingMenu';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import type { GenerateDialogState } from './ImageCanvasEditorTypes';
+import {
+  EDITOR_IMAGE_DIMENSION_OPTIONS,
+  EDITOR_IMAGE_MODEL_OPTIONS,
+  getEditorImageModelDisplayName,
+  IMAGE_MODEL_NANOBANANA2,
+  normalizeEditorImageModel,
+  resizeGenerationPlaceholderToImageSelection,
+  resolveEditorImageSizeLabel,
+} from './ImageCanvasGenerationModel';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasGenerationImageOptionsViewProps = {
+  dialog: GenerateDialogState;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  includeDimensions: boolean;
+  onRememberImageModel: (model: string) => void;
+  optionLabelPrefix?: string;
+  cost?: number;
+  submitLabel?: string;
+  submitAriaLabel?: string;
+  renderEditorPortal?: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle?: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+};
+
+type OpenPanel = 'dimensions' | 'model' | null;
+
+function resetFailedDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function getImageDimensionOptions(model: string | null | undefined) {
+  return (
+    EDITOR_IMAGE_DIMENSION_OPTIONS[
+      (model ?? IMAGE_MODEL_NANOBANANA2) as keyof typeof EDITOR_IMAGE_DIMENSION_OPTIONS
+    ] ?? EDITOR_IMAGE_DIMENSION_OPTIONS[IMAGE_MODEL_NANOBANANA2]
+  );
+}
+
+function normalizeImageDialogSelection(dialog: GenerateDialogState) {
+  const model = normalizeEditorImageModel(dialog.imageModel ?? IMAGE_MODEL_NANOBANANA2);
+  const options = getImageDimensionOptions(model);
+  const aspectRatios = options.aspectRatios as readonly string[];
+  const imageSizes = options.imageSizes as readonly string[];
+  return {
+    model,
+    aspectRatio:
+      dialog.aspectRatio && aspectRatios.includes(dialog.aspectRatio)
+        ? dialog.aspectRatio
+        : (options.aspectRatios[0] ?? '1:1'),
+    imageSize:
+      dialog.imageSize && imageSizes.includes(dialog.imageSize)
+        ? dialog.imageSize
+        : (options.imageSizes.find((size) => size === '1K') ??
+          options.imageSizes[0] ??
+          '1K'),
+    options,
+  };
+}
+
+function OptionChoice({
+  children,
+  selected,
+  className,
+  onClick,
+}: {
+  children: ReactNode;
+  selected: boolean;
+  className?: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className={['image-canvas-editor__option-popover-choice', className]
+        .filter(Boolean)
+        .join(' ')}
+      aria-pressed={selected}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function ImageCanvasGenerationImageOptionsView({
+  dialog,
+  setGenerateDialog,
+  includeDimensions,
+  onRememberImageModel,
+  optionLabelPrefix,
+  cost,
+  submitLabel = '生成',
+  submitAriaLabel = '生成',
+  renderEditorPortal = (node) => node,
+  buildPortalMenuStyle = () => ({}),
+}: ImageCanvasGenerationImageOptionsViewProps) {
+  const [openPanel, setOpenPanel] = useState<OpenPanel>(null);
+  const dimensionsButtonRef = useRef<HTMLButtonElement | null>(null);
+  const modelButtonRef = useRef<HTMLButtonElement | null>(null);
+  const selection = normalizeImageDialogSelection(dialog);
+  const selectedModelLabel = getEditorImageModelDisplayName(selection.model);
+  const selectedSizeLabel = resolveEditorImageSizeLabel({
+    aspectRatio: selection.aspectRatio,
+    imageSize: selection.imageSize,
+  });
+  const isGenerating = dialog.status === 'generating';
+  const labelPrefix = optionLabelPrefix ?? '生成图片';
+  const dismissOpenPanel = useCallback(() => setOpenPanel(null), []);
+
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: openPanel !== null,
+    boundaryRefs: [dimensionsButtonRef, modelButtonRef],
+    onDismiss: dismissOpenPanel,
+  });
+
+  const updateDialog = (patch: Partial<GenerateDialogState>) => {
+    setGenerateDialog((currentDialog) =>
+      currentDialog && currentDialog.mode === dialog.mode
+        ? resizeGenerationPlaceholderToImageSelection({
+            ...resetFailedDialogStatus(currentDialog),
+            ...patch,
+          })
+        : currentDialog,
+    );
+  };
+
+  const updateImageModel = (model: string) => {
+    onRememberImageModel(model);
+    setGenerateDialog((currentDialog) => {
+      if (!currentDialog || currentDialog.mode !== dialog.mode) {
+        return currentDialog;
+      }
+      if (!includeDimensions) {
+        return {
+          ...resetFailedDialogStatus(currentDialog),
+          imageModel: model,
+        };
+      }
+      const nextOptions = getImageDimensionOptions(model);
+      const nextAspectRatios = nextOptions.aspectRatios as readonly string[];
+      const nextImageSizes = nextOptions.imageSizes as readonly string[];
+      const nextDialog = {
+        ...resetFailedDialogStatus(currentDialog),
+        imageModel: model,
+        aspectRatio:
+          currentDialog.aspectRatio &&
+          nextAspectRatios.includes(currentDialog.aspectRatio)
+            ? currentDialog.aspectRatio
+            : (nextOptions.aspectRatios[0] ?? '1:1'),
+        imageSize:
+          currentDialog.imageSize &&
+          nextImageSizes.includes(currentDialog.imageSize)
+            ? currentDialog.imageSize
+            : (nextOptions.imageSizes.find((size) => size === '1K') ??
+              nextOptions.imageSizes[0] ??
+              '1K'),
+      };
+      return resizeGenerationPlaceholderToImageSelection(nextDialog);
+    });
+  };
+
+  const togglePanel = (panel: Exclude<OpenPanel, null>) => {
+    setOpenPanel((currentPanel) => (currentPanel === panel ? null : panel));
+  };
+
+  return (
+    <>
+      {includeDimensions ? (
+        <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions">
+          <PlatformInlineOptionButton
+            ref={dimensionsButtonRef}
+            className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+            aria-label={`${labelPrefix}尺寸 ${selectedSizeLabel}`}
+            aria-expanded={openPanel === 'dimensions'}
+            disabled={isGenerating}
+            trailingIcon={<ChevronDown className="h-3 w-3" />}
+            onClick={() => togglePanel('dimensions')}
+          >
+            {selectedSizeLabel}
+          </PlatformInlineOptionButton>
+          {openPanel === 'dimensions'
+            ? renderEditorPortal(
+                <PlatformFloatingMenu
+                  className="image-canvas-editor__option-popover image-canvas-editor__portal-menu"
+                  label={`${labelPrefix}尺寸选项`}
+                  placement="top-start"
+                  style={buildPortalMenuStyle(
+                    dimensionsButtonRef.current,
+                    'above',
+                  )}
+                  onPointerDown={(event) => event.stopPropagation()}
+                >
+                  <div className="image-canvas-editor__option-popover-sections">
+                    <div className="image-canvas-editor__option-popover-section">
+                      <span className="image-canvas-editor__option-popover-title">
+                        比例
+                      </span>
+                      <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--card">
+                        {selection.options.aspectRatios.map((aspectRatio) => (
+                          <OptionChoice
+                            key={aspectRatio}
+                            selected={selection.aspectRatio === aspectRatio}
+                            className="image-canvas-editor__option-popover-choice--ratio"
+                            onClick={() => updateDialog({ aspectRatio })}
+                          >
+                            <span
+                              className="image-canvas-editor__ratio-wireframe"
+                              data-ratio={aspectRatio}
+                              aria-hidden="true"
+                            />
+                            <span>{aspectRatio}</span>
+                          </OptionChoice>
+                        ))}
+                      </div>
+                    </div>
+                    <div className="image-canvas-editor__option-popover-section">
+                      <span className="image-canvas-editor__option-popover-title">
+                        尺寸
+                      </span>
+                      <div className="image-canvas-editor__option-popover-items">
+                        {selection.options.imageSizes.map((imageSize) => (
+                          <OptionChoice
+                            key={imageSize}
+                            selected={selection.imageSize === imageSize}
+                            onClick={() => updateDialog({ imageSize })}
+                          >
+                            {imageSize}
+                          </OptionChoice>
+                        ))}
+                      </div>
+                    </div>
+                  </div>
+                </PlatformFloatingMenu>,
+              )
+            : null}
+        </div>
+      ) : null}
+      <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--model">
+        <PlatformInlineOptionButton
+          ref={modelButtonRef}
+          className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--model"
+          aria-label={`${labelPrefix}模型 ${selectedModelLabel}`}
+          aria-expanded={openPanel === 'model'}
+          disabled={isGenerating}
+          trailingIcon={<ChevronDown className="h-3 w-3" />}
+          onClick={() => togglePanel('model')}
+        >
+          <span className="image-canvas-editor__model-trigger-label">
+            <span className="image-canvas-editor__model-icon" aria-hidden="true">
+              <Cpu />
+            </span>
+            <span>{selectedModelLabel}</span>
+          </span>
+        </PlatformInlineOptionButton>
+        {openPanel === 'model'
+          ? renderEditorPortal(
+              <PlatformFloatingMenu
+                className="image-canvas-editor__option-popover image-canvas-editor__option-popover--model image-canvas-editor__portal-menu"
+                label={`${labelPrefix}模型选项`}
+                placement="top-start"
+                style={buildPortalMenuStyle(modelButtonRef.current, 'above')}
+                onPointerDown={(event) => event.stopPropagation()}
+              >
+                <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--model">
+                  {EDITOR_IMAGE_MODEL_OPTIONS.map((option) => {
+                    const selected = selection.model === option.value;
+                    return (
+                      <OptionChoice
+                        key={option.value}
+                        selected={selected}
+                        className="image-canvas-editor__option-popover-choice--model"
+                        onClick={() => updateImageModel(option.value)}
+                      >
+                        <span
+                          className="image-canvas-editor__model-icon"
+                          aria-hidden="true"
+                        >
+                          <Cpu />
+                        </span>
+                        <span>{option.label}</span>
+                        <Check
+                          className="image-canvas-editor__option-selected-check"
+                          data-visible={selected}
+                          aria-hidden="true"
+                        />
+                      </OptionChoice>
+                    );
+                  })}
+                </div>
+              </PlatformFloatingMenu>,
+            )
+          : null}
+      </div>
+      {typeof cost === 'number' ? (
+        <PlatformActionButton
+          type="submit"
+          tone="secondary"
+          size="xs"
+          shape="pill"
+          className="image-canvas-editor__generation-submit"
+          disabled={isGenerating}
+          aria-label={submitAriaLabel}
+        >
+          {isGenerating ? (
+            '生成中'
+          ) : (
+            <>
+              <span>{submitLabel}</span>
+              <span className="image-canvas-editor__mud-point-inline">
+                {cost}泥点
+              </span>
+            </>
+          )}
+        </PlatformActionButton>
+      ) : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts b/src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts
new file mode 100644
index 000000000..13a4e756c
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts
@@ -0,0 +1,532 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasGenerationInputs,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  createAudioResultLayer,
+  createCharacterAnimationResultLayer,
+  createGeneratedResultLayer,
+  createIconSpritesheetResultLayers,
+  createQuickEditResultLayer,
+  createVideoResultLayer,
+} from './ImageCanvasGenerationLayerModel';
+
+function createGenerated(overrides = {}) {
+  return {
+    imageSrc: 'data:image/png;base64,generated',
+    width: 1024,
+    height: 1024,
+    sourceType: 'generated' as const,
+    prompt: '生成提示词',
+    actualPrompt: '实际提示词',
+    model: 'gpt-image-2',
+    provider: 'VectorEngine',
+    taskId: 'task-generated',
+    objectKey: 'generated/object.png',
+    assetObjectId: 'asset-object-generated',
+    ...overrides,
+  };
+}
+
+function createSourceLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '源图',
+    src: 'data:image/png;base64,source',
+    x: 120,
+    y: 140,
+    width: 320,
+    height: 240,
+    originalWidth: 1536,
+    originalHeight: 1024,
+    zIndex: 2,
+    sourceType: 'generated',
+    groupId: 'group-a',
+    assetKind: 'spec',
+    ...overrides,
+  };
+}
+
+function createGenerationInputs(): CanvasGenerationInputs {
+  return {
+    fields: [{ title: '生成提示词', value: '生成提示词' }],
+    references: [],
+  };
+}
+
+describe('ImageCanvasGenerationLayerModel', () => {
+  it('creates generated result layers centered on the active placeholder', () => {
+    const layer = createGeneratedResultLayer({
+      generated: createGenerated({ width: 2048, height: 1152 }),
+      generatedIndex: 7,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      frame: {
+        x: 80,
+        y: 60,
+        width: 560,
+        height: 315,
+        originalWidth: 2048,
+        originalHeight: 1152,
+      },
+      assetKind: 'spec',
+      title: '图标规范 7',
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-generated-7',
+      resourceId: 'local-resource-generated-7',
+      title: '图标规范 7',
+      x: -664,
+      y: -358.5,
+      width: 2048,
+      height: 1152,
+      originalWidth: 2048,
+      originalHeight: 1152,
+      zIndex: 17,
+      sourceType: 'generated',
+      assetKind: 'spec',
+      prompt: '生成提示词',
+      actualPrompt: '实际提示词',
+      objectKey: 'generated/object.png',
+      assetObjectId: 'asset-object-generated',
+    });
+    expect(layer.generationInputs?.fields[0]?.value).toBe('生成提示词');
+  });
+
+  it('keeps publication material result dimensions constrained by the active placeholder', () => {
+    const layer = createGeneratedResultLayer({
+      generated: createGenerated({ width: 1024, height: 1024 }),
+      generatedIndex: 8,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      frame: {
+        x: 180,
+        y: 120,
+        width: 360,
+        height: 640,
+        originalWidth: 720,
+        originalHeight: 1280,
+      },
+      assetKind: 'publication-material',
+      title: '8 宣发素材',
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-generated-8',
+      title: '8 宣发素材',
+      width: 720,
+      height: 1280,
+      originalWidth: 720,
+      originalHeight: 1280,
+      assetKind: 'publication-material',
+    });
+  });
+
+  it('keeps publication cover image results at the 4:3 workflow dimensions', () => {
+    const layer = createGeneratedResultLayer({
+      generated: createGenerated({ width: 1024, height: 1024 }),
+      generatedIndex: 9,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      frame: {
+        x: 100,
+        y: 100,
+        width: 480,
+        height: 360,
+        originalWidth: 720,
+        originalHeight: 540,
+      },
+      assetKind: 'publication-material',
+      title: '9 宣发素材',
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      width: 720,
+      height: 540,
+      originalWidth: 720,
+      originalHeight: 540,
+      assetKind: 'publication-material',
+    });
+  });
+
+  it('uses backend-persisted resource and asset snapshots for generated layers', () => {
+    const generationInputs = createGenerationInputs();
+    const layer = createGeneratedResultLayer({
+      generated: createGenerated({
+        resource: {
+          resourceId: 'resource-generated-bff',
+          projectId: 'editor-project-1',
+          imageSrc: 'data:image/png;base64,generated',
+          objectKey: 'generated/from-resource.png',
+          assetObjectId: 'asset-object-from-resource',
+          width: 1024,
+          height: 1024,
+          sourceType: 'generated',
+          assetKind: 'character',
+          generationInputs,
+        },
+        asset: {
+          assetId: 'asset-generated-bff',
+          folderId: 'user-1:asset-folder:project',
+          label: '角色形象',
+          imageSrc: 'data:image/png;base64,generated',
+          objectKey: 'generated/from-asset.png',
+          assetObjectId: 'asset-object-from-asset',
+          width: 1024,
+          height: 1024,
+          sourceType: 'generated',
+          assetKind: 'character',
+          generationInputs,
+        },
+      }),
+      generatedIndex: 9,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 0, y: 0, scale: 1 },
+      assetKind: 'spec',
+      generationInputs: {
+        fields: [{ title: '旧输入', value: '本地兜底' }],
+        references: [],
+      },
+    });
+
+    expect(layer).toMatchObject({
+      resourceId: 'resource-generated-bff',
+      sourceAssetId: 'asset-generated-bff',
+      objectKey: 'generated/from-resource.png',
+      assetObjectId: 'asset-object-from-resource',
+      assetKind: 'character',
+    });
+    expect(layer.generationInputs?.fields[0]?.value).toBe('生成提示词');
+    expect(layer.generatedAssetSnapshot?.assetId).toBe('asset-generated-bff');
+  });
+
+  it('creates edit result layers beside the source image', () => {
+    const sourceLayer = createSourceLayer();
+    const layer = createGeneratedResultLayer({
+      generated: createGenerated({ prompt: '修改要求' }),
+      generatedIndex: 8,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 0, y: 0, scale: 1 },
+      sourceLayer,
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-edit-8',
+      resourceId: 'local-resource-edit-8',
+      title: '源图 修改结果',
+      x: 472,
+      y: 140,
+      width: 1024,
+      height: 1024,
+      sourceResourceId: 'resource-source',
+      prompt: '修改要求',
+    });
+  });
+
+  it('creates quick edit layers centered on the generating placeholder', () => {
+    const sourceLayer = createSourceLayer();
+    const layer = createQuickEditResultLayer({
+      generated: createGenerated({ width: 1536, height: 1024 }),
+      generatedIndex: 10,
+      sourceLayer,
+      generationInputs: createGenerationInputs(),
+      frame: {
+        x: 600,
+        y: 300,
+        width: 320,
+        height: 240,
+        originalWidth: 1536,
+        originalHeight: 1024,
+      },
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-quick-edit-10',
+      x: -8,
+      y: -92,
+      width: 1536,
+      height: 1024,
+    });
+  });
+
+  it('creates quick edit layers with source group and asset kind preserved', () => {
+    const sourceLayer = createSourceLayer();
+    const layer = createQuickEditResultLayer({
+      generated: createGenerated({ width: 1536, height: 1024 }),
+      generatedIndex: 9,
+      sourceLayer,
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-quick-edit-9',
+      resourceId: 'local-resource-quick-edit-9',
+      title: '源图 快速编辑',
+      x: 472,
+      y: 140,
+      width: 1536,
+      height: 1024,
+      originalWidth: 1536,
+      originalHeight: 1024,
+      sourceResourceId: 'resource-source',
+      groupId: 'group-a',
+      assetKind: 'spec',
+    });
+  });
+
+  it('creates wrapped icon layers with icon metadata', () => {
+    const layers = createIconSpritesheetResultLayers({
+      generated: {
+        spritesheetImageSrc: 'data:image/png;base64,sheet',
+        spritesheetWidth: 512,
+        spritesheetHeight: 512,
+        iconImageSrcs: [],
+        prompt: '图标 prompt',
+        actualPrompt: '图标 actual prompt',
+        model: 'gpt-image-2',
+        provider: 'VectorEngine',
+        taskId: 'task-icons',
+        priceMudPoints: 20,
+      },
+      iconResults: [
+        {
+          name: '返回按钮',
+          imageSrc: 'data:image/png;base64,back',
+          width: 256,
+          height: 256,
+        },
+        {
+          name: '设置按钮',
+          imageSrc: 'data:image/png;base64,settings',
+          width: 512,
+          height: 256,
+        },
+        {
+          name: '提示按钮',
+          imageSrc: 'data:image/png;base64,hint',
+          width: 128,
+          height: 128,
+        },
+      ],
+      startIndex: 11,
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 0, y: 0, scale: 1 },
+      frame: {
+        x: 200,
+        y: 100,
+        width: 360,
+        height: 360,
+        originalWidth: 512,
+        originalHeight: 512,
+      },
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layers).toHaveLength(4);
+    expect(layers[0]).toMatchObject({
+      id: 'layer-icon-spritesheet-11',
+      title: '图标素材图集 11',
+      x: 200,
+      y: 100,
+      width: 512,
+      height: 512,
+      assetKind: 'icon-spritesheet',
+      prompt: '图标 prompt',
+      actualPrompt: '图标 actual prompt',
+    });
+    expect(layers[1]).toMatchObject({
+      id: 'layer-icon-12',
+      title: '返回按钮',
+      x: 744,
+      y: 100,
+      width: 256,
+      height: 256,
+      assetKind: 'icon',
+      prompt: '图标 prompt',
+      actualPrompt: '图标 actual prompt',
+    });
+    expect(layers[2]).toMatchObject({
+      id: 'layer-icon-13',
+      title: '设置按钮',
+      x: 744,
+      y: 380,
+      width: 512,
+      height: 256,
+      assetKind: 'icon',
+    });
+    expect(layers[3]).toMatchObject({
+      id: 'layer-icon-14',
+      title: '提示按钮',
+      x: 744,
+      y: 660,
+      width: 128,
+      height: 128,
+      assetKind: 'icon',
+    });
+  });
+
+  it('creates audio result layers centered on the active placeholder', () => {
+    const layer = createAudioResultLayer({
+      generated: {
+        audioSrc: '/generated-character-drafts/editor-audios/sfx.mp3',
+        objectKey: 'generated-character-drafts/editor-audios/sfx.mp3',
+        assetObjectId: 'assetobj-audio-1',
+        width: 420,
+        height: 120,
+        sourceType: 'generated',
+        prompt: '金币掉落叮当声',
+        actualPrompt: '金币掉落叮当声',
+        model: 'audio1.0',
+        provider: 'VectorEngine',
+        taskId: 'sound-task-1',
+        priceMudPoints: 10,
+        audioKind: 'sound-effect',
+        durationSeconds: 75,
+      },
+      generatedIndex: 14,
+      title: '游戏音效 14',
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      frame: {
+        x: 80,
+        y: 60,
+        width: 420,
+        height: 120,
+        originalWidth: 420,
+        originalHeight: 120,
+      },
+      generationInputs: {
+        fields: [{ title: 'prompt', value: '金币掉落叮当声' }],
+        references: [],
+      },
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-audio-14',
+      resourceId: 'local-resource-audio-14',
+      title: '游戏音效 14',
+      src: '/generated-character-drafts/editor-audios/sfx.mp3',
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+      x: 80,
+      y: 60,
+      width: 420,
+      height: 120,
+      originalWidth: 420,
+      originalHeight: 120,
+      sourceType: 'generated',
+      prompt: '金币掉落叮当声',
+      model: 'audio1.0',
+      provider: 'VectorEngine',
+      taskId: 'sound-task-1',
+      objectKey: 'generated-character-drafts/editor-audios/sfx.mp3',
+      assetObjectId: 'assetobj-audio-1',
+      durationSeconds: 75,
+    });
+  });
+
+  it('creates video result layers with OSS asset identity', () => {
+    const layer = createVideoResultLayer({
+      generated: {
+        videoSrc: '/generated-character-drafts/editor-videos/video.mp4',
+        objectKey: 'generated-character-drafts/editor-videos/video.mp4',
+        assetObjectId: 'assetobj-video-1',
+        width: 1280,
+        height: 720,
+        sourceType: 'generated',
+        prompt: '开场动画',
+        actualPrompt: '开场动画',
+        model: 'seedance2.0-fast',
+        provider: 'VectorEngine',
+        taskId: 'video-task-1',
+        priceMudPoints: 40,
+      },
+      generatedIndex: 15,
+      title: '生成视频 15',
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      generationInputs: createGenerationInputs(),
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-video-15',
+      src: '/generated-character-drafts/editor-videos/video.mp4',
+      mediaType: 'video',
+      assetKind: 'video',
+      objectKey: 'generated-character-drafts/editor-videos/video.mp4',
+      assetObjectId: 'assetobj-video-1',
+    });
+  });
+
+  it('creates character animation result layers with playable video preview and frame metadata', () => {
+    const layer = createCharacterAnimationResultLayer({
+      generated: {
+        taskId: 'character-animation-task-1',
+        model: 'seedance2.0-fast',
+        prompt: '待机动作',
+        previewVideoPath: '/generated-character-drafts/editor/preview.mp4',
+        frames: [
+          {
+            frameIndex: 1,
+            imageSrc: '/generated-character-drafts/editor/frame1.png',
+            width: 1024,
+            height: 1024,
+          },
+        ],
+        frameCount: 32,
+        durationSeconds: 4,
+        fps: 8,
+        priceMudPoints: 40,
+      },
+      generatedIndex: 15,
+      title: '角色动作',
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+      frame: {
+        x: 80,
+        y: 60,
+        width: 420,
+        height: 420,
+        originalWidth: 1024,
+        originalHeight: 1024,
+      },
+      generationInputs: {
+        fields: [{ title: '动作描述', value: '待机动作' }],
+        references: [],
+      },
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-character-animation-15',
+      resourceId: 'local-resource-character-animation-15',
+      title: '角色动作',
+      src: '/generated-character-drafts/editor/preview.mp4',
+      mediaType: 'video',
+      thumbnailSrc: '/generated-character-drafts/editor/frame1.png',
+      x: -222,
+      y: -242,
+      width: 1024,
+      height: 1024,
+      originalWidth: 1024,
+      originalHeight: 1024,
+      zIndex: 25,
+      sourceType: 'generated',
+      prompt: '待机动作',
+      actualPrompt: '待机动作',
+      model: 'seedance2.0-fast',
+      provider: 'ark',
+      taskId: 'character-animation-task-1',
+      assetKind: 'character-animation',
+      durationSeconds: 4,
+    });
+    expect(layer?.generationInputs?.fields[0]?.value).toBe('待机动作');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationLayerModel.ts b/src/components/image-editor/ImageCanvasGenerationLayerModel.ts
new file mode 100644
index 000000000..c72d88959
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationLayerModel.ts
@@ -0,0 +1,519 @@
+import type {
+  EditorAudioGenerationResult,
+  EditorCharacterAnimationGenerationResult,
+  EditorIconSpritesheetGenerationResult,
+  EditorIconSpritesheetIconResult,
+  EditorImageGenerationResult,
+  EditorVideoGenerationResult,
+} from '../../services/image-editor/editorProjectClient';
+import { resolveLayerResolutionSize } from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationInputs,
+  CanvasLayer,
+  CanvasViewport,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import {
+  ICON_FRAME_DISPLAY_SIZE,
+  ICON_FRAME_ORIGINAL_SIZE,
+} from './ImageCanvasGenerationModel';
+
+type CanvasSize = { width: number; height: number };
+
+type GeneratedResultLayerOptions = {
+  generated: EditorImageGenerationResult;
+  generatedIndex: number;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  sourceLayer?: CanvasLayer;
+  frame?: GenerateDialogState['placeholder'];
+  assetKind?: CanvasLayer['assetKind'];
+  title?: string;
+  generationInputs?: CanvasGenerationInputs;
+};
+
+type QuickEditResultLayerOptions = {
+  generated: EditorImageGenerationResult;
+  generatedIndex: number;
+  sourceLayer: CanvasLayer;
+  generationInputs: CanvasGenerationInputs;
+  mode?: 'quick-edit' | 'redraw';
+  frame?: GenerateDialogState['placeholder'];
+};
+
+type IconSpritesheetResultLayerOptions = {
+  generated: EditorIconSpritesheetGenerationResult;
+  iconResults: EditorIconSpritesheetIconResult[];
+  startIndex: number;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  generationInputs: CanvasGenerationInputs;
+  frame?: GenerateDialogState['placeholder'];
+  spritesheetTitle?: string;
+};
+
+type VideoResultLayerOptions = {
+  generated: EditorVideoGenerationResult;
+  generatedIndex: number;
+  title: string;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  generationInputs: CanvasGenerationInputs;
+  frame?: GenerateDialogState['placeholder'];
+  sourceLayer?: CanvasLayer;
+  assetKind?: CanvasLayer['assetKind'];
+};
+
+type AudioResultLayerOptions = {
+  generated: EditorAudioGenerationResult;
+  generatedIndex: number;
+  title: string;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  generationInputs: CanvasGenerationInputs;
+  frame?: GenerateDialogState['placeholder'];
+};
+
+type CharacterAnimationResultLayerOptions = {
+  generated: EditorCharacterAnimationGenerationResult;
+  generatedIndex: number;
+  title: string;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  generationInputs: CanvasGenerationInputs;
+  frame?: GenerateDialogState['placeholder'];
+  sourceLayer?: CanvasLayer;
+};
+
+function getViewportWorldCenter({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}) {
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  return {
+    x: (canvasSize.width / 2 - viewport.x) / safeScale,
+    y: (canvasSize.height / 2 - viewport.y) / safeScale,
+  };
+}
+
+function applyGeneratedMetadata(
+  layer: CanvasLayer,
+  generated: EditorImageGenerationResult,
+  generationInputs: CanvasGenerationInputs | undefined,
+): CanvasLayer {
+  const resource = generated.resource;
+  const asset = generated.asset;
+  return {
+    ...layer,
+    resourceId: resource?.resourceId ?? layer.resourceId,
+    sourceAssetId: asset?.assetId ?? layer.sourceAssetId,
+    prompt: generated.prompt,
+    actualPrompt: generated.actualPrompt ?? generated.prompt,
+    model: generated.model,
+    provider: generated.provider,
+    taskId: generated.taskId,
+    objectKey: resource?.objectKey ?? generated.objectKey,
+    assetObjectId: resource?.assetObjectId ?? generated.assetObjectId,
+    assetKind:
+      (resource?.assetKind as CanvasLayer['assetKind'] | undefined) ??
+      layer.assetKind,
+    generationInputs: resource?.generationInputs ?? generationInputs,
+    generatedAssetSnapshot: asset,
+  };
+}
+
+export function createGeneratedResultLayer({
+  generated,
+  generatedIndex,
+  canvasSize,
+  viewport,
+  sourceLayer,
+  frame,
+  assetKind,
+  title,
+  generationInputs,
+}: GeneratedResultLayerOptions): CanvasLayer {
+  const originalWidth = frame?.originalWidth || generated.width || 1024;
+  const originalHeight = frame?.originalHeight || generated.height || 1024;
+  const { width, height } = resolveLayerResolutionSize(
+    originalWidth,
+    originalHeight,
+    { width: 1024, height: 1024 },
+  );
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const frameX =
+    frame && frame.width > 0
+      ? frame.x + frame.width / 2 - width / 2
+      : undefined;
+  const frameY =
+    frame && frame.height > 0
+      ? frame.y + frame.height / 2 - height / 2
+      : undefined;
+
+  return applyGeneratedMetadata(
+    {
+      id: sourceLayer
+        ? `layer-edit-${generatedIndex}`
+        : `layer-generated-${generatedIndex}`,
+      resourceId: sourceLayer
+        ? `local-resource-edit-${generatedIndex}`
+        : `local-resource-generated-${generatedIndex}`,
+      title: sourceLayer
+        ? `${sourceLayer.title} 修改结果`
+        : (title ?? `生成图片 ${generatedIndex}`),
+      src: generated.imageSrc,
+      x: sourceLayer
+        ? sourceLayer.x + sourceLayer.width + 32
+        : (frameX ?? worldCenter.x - width / 2),
+      y: sourceLayer ? sourceLayer.y : (frameY ?? worldCenter.y - height / 2),
+      width,
+      height,
+      originalWidth,
+      originalHeight,
+      zIndex: generatedIndex + 10,
+      sourceType: generated.sourceType,
+      assetKind,
+      sourceResourceId: sourceLayer?.resourceId,
+    },
+    generated,
+    generationInputs,
+  );
+}
+
+export function createQuickEditResultLayer({
+  generated,
+  generatedIndex,
+  sourceLayer,
+  generationInputs,
+  mode = 'quick-edit',
+  frame,
+}: QuickEditResultLayerOptions): CanvasLayer {
+  const originalWidth =
+    frame?.originalWidth || generated.width || sourceLayer.originalWidth || 1024;
+  const originalHeight =
+    frame?.originalHeight ||
+    generated.height ||
+    sourceLayer.originalHeight ||
+    1024;
+  const { width, height } = resolveLayerResolutionSize(
+    originalWidth,
+    originalHeight,
+    {
+      width: sourceLayer.width,
+      height: sourceLayer.height,
+    },
+  );
+  const frameX =
+    frame && frame.width > 0
+      ? frame.x + frame.width / 2 - width / 2
+      : undefined;
+  const frameY =
+    frame && frame.height > 0
+      ? frame.y + frame.height / 2 - height / 2
+      : undefined;
+
+  return applyGeneratedMetadata(
+    {
+      id: `layer-quick-edit-${generatedIndex}`,
+      resourceId: `local-resource-quick-edit-${generatedIndex}`,
+      title: `${sourceLayer.title} ${mode === 'redraw' ? '重绘' : '快速编辑'}`,
+      src: generated.imageSrc,
+      x: frameX ?? sourceLayer.x + sourceLayer.width + 32,
+      y: frameY ?? sourceLayer.y,
+      width,
+      height,
+      originalWidth,
+      originalHeight,
+      zIndex: generatedIndex + 10,
+      sourceType: generated.sourceType,
+      sourceResourceId: sourceLayer.resourceId,
+      groupId: sourceLayer.groupId,
+      assetKind: sourceLayer.assetKind,
+    },
+    generated,
+    generationInputs,
+  );
+}
+
+export function createIconSpritesheetResultLayers({
+  generated,
+  iconResults,
+  startIndex,
+  canvasSize,
+  viewport,
+  generationInputs,
+  frame,
+  spritesheetTitle,
+}: IconSpritesheetResultLayerOptions): CanvasLayer[] {
+  const spritesheetResource = generated.spritesheetResource;
+  const spritesheetAsset = generated.spritesheetAsset;
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const startX =
+    frame?.x ?? worldCenter.x - ICON_FRAME_DISPLAY_SIZE.width / 2;
+  const startY =
+    frame?.y ?? worldCenter.y - ICON_FRAME_DISPLAY_SIZE.height / 2;
+  const spacing = 24;
+  const maxRowWidth = 560;
+  const spritesheetOriginalWidth =
+    generated.spritesheetWidth || ICON_FRAME_ORIGINAL_SIZE.width;
+  const spritesheetOriginalHeight =
+    generated.spritesheetHeight || ICON_FRAME_ORIGINAL_SIZE.height;
+  const spritesheetDisplaySize = resolveLayerResolutionSize(
+    spritesheetOriginalWidth,
+    spritesheetOriginalHeight,
+    ICON_FRAME_DISPLAY_SIZE,
+  );
+  const spritesheetLayer: CanvasLayer = {
+    id: `layer-icon-spritesheet-${startIndex}`,
+    resourceId:
+      spritesheetResource?.resourceId ??
+      `local-resource-icon-spritesheet-${startIndex}`,
+    title: spritesheetTitle ?? `图标素材图集 ${startIndex}`,
+    src: generated.spritesheetImageSrc,
+    x: startX,
+    y: startY,
+    width: spritesheetDisplaySize.width,
+    height: spritesheetDisplaySize.height,
+    originalWidth: spritesheetOriginalWidth,
+    originalHeight: spritesheetOriginalHeight,
+    zIndex: startIndex + 10,
+    sourceType: 'generated',
+    prompt: generated.prompt,
+    actualPrompt: generated.actualPrompt ?? generated.prompt,
+    model: generated.model,
+    provider: generated.provider,
+    taskId: generated.taskId,
+    assetKind: 'icon-spritesheet',
+    sourceAssetId: spritesheetAsset?.assetId,
+    objectKey: spritesheetResource?.objectKey ?? undefined,
+    assetObjectId: spritesheetResource?.assetObjectId ?? undefined,
+    generationInputs:
+      spritesheetResource?.generationInputs ?? generationInputs,
+    generatedAssetSnapshot: spritesheetAsset,
+  };
+  const iconStartX = startX + spritesheetDisplaySize.width + 32;
+  let cursorX = iconStartX;
+  let cursorY = startY;
+  let rowHeight = 0;
+
+  const iconLayers = iconResults.map((icon, index) => {
+    const resource = icon.resource;
+    const asset = icon.asset;
+    const originalWidth = icon.width || 128;
+    const originalHeight = icon.height || 128;
+    const { width, height } = resolveLayerResolutionSize(
+      originalWidth,
+      originalHeight,
+      { width: 128, height: 128 },
+    );
+    if (cursorX > iconStartX && cursorX + width - iconStartX > maxRowWidth) {
+      cursorX = iconStartX;
+      cursorY += rowHeight + spacing;
+      rowHeight = 0;
+    }
+
+    const generatedIndex = startIndex + index + 1;
+    const layer: CanvasLayer = {
+      id: `layer-icon-${generatedIndex}`,
+      resourceId: resource?.resourceId ?? `local-resource-icon-${generatedIndex}`,
+      title: icon.name,
+      src: icon.imageSrc,
+      x: cursorX,
+      y: cursorY,
+      width,
+      height,
+      originalWidth,
+      originalHeight,
+      zIndex: generatedIndex + 10,
+      sourceType: 'generated',
+      prompt: generated.prompt,
+      actualPrompt: generated.actualPrompt ?? generated.prompt,
+      model: generated.model,
+      provider: generated.provider,
+      taskId: generated.taskId,
+      assetKind: 'icon',
+      sourceAssetId: asset?.assetId,
+      objectKey: resource?.objectKey ?? undefined,
+      assetObjectId: resource?.assetObjectId ?? undefined,
+      generationInputs: resource?.generationInputs ?? generationInputs,
+      generatedAssetSnapshot: asset,
+    };
+
+    cursorX += width + spacing;
+    rowHeight = Math.max(rowHeight, height);
+    return layer;
+  });
+
+  return [spritesheetLayer, ...iconLayers];
+}
+
+export function createVideoResultLayer({
+  generated,
+  generatedIndex,
+  title,
+  canvasSize,
+  viewport,
+  generationInputs,
+  frame,
+  sourceLayer,
+  assetKind = 'video',
+}: VideoResultLayerOptions): CanvasLayer {
+  const originalWidth = generated.width || 1280;
+  const originalHeight = generated.height || 720;
+  const { width, height } = resolveLayerResolutionSize(
+    originalWidth,
+    originalHeight,
+    { width: 560, height: 315 },
+  );
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const frameX =
+    frame && frame.width > 0
+      ? frame.x + frame.width / 2 - width / 2
+      : undefined;
+  const frameY =
+    frame && frame.height > 0
+      ? frame.y + frame.height / 2 - height / 2
+      : undefined;
+
+  return {
+    id: `layer-video-${generatedIndex}`,
+    resourceId: `local-resource-video-${generatedIndex}`,
+    title,
+    src: generated.videoSrc,
+    mediaType: 'video',
+    assetKind,
+    x: frameX ?? worldCenter.x - width / 2,
+    y: frameY ?? worldCenter.y - height / 2,
+    width,
+    height,
+    originalWidth,
+    originalHeight,
+    zIndex: generatedIndex + 10,
+    sourceType: generated.sourceType,
+    prompt: generated.prompt,
+    actualPrompt: generated.actualPrompt ?? generated.prompt,
+    model: generated.model,
+    provider: generated.provider,
+    taskId: generated.taskId,
+    objectKey: generated.objectKey,
+    assetObjectId: generated.assetObjectId,
+    sourceResourceId: sourceLayer?.resourceId,
+    groupId: sourceLayer?.groupId,
+    generationInputs,
+  };
+}
+
+export function createAudioResultLayer({
+  generated,
+  generatedIndex,
+  title,
+  canvasSize,
+  viewport,
+  generationInputs,
+  frame,
+}: AudioResultLayerOptions): CanvasLayer {
+  const originalWidth = generated.width || 420;
+  const originalHeight = generated.height || 120;
+  const { width, height } = resolveLayerResolutionSize(
+    originalWidth,
+    originalHeight,
+    { width: 420, height: 120 },
+  );
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const frameX =
+    frame && frame.width > 0
+      ? frame.x + frame.width / 2 - width / 2
+      : undefined;
+  const frameY =
+    frame && frame.height > 0
+      ? frame.y + frame.height / 2 - height / 2
+      : undefined;
+
+  return {
+    id: `layer-audio-${generatedIndex}`,
+    resourceId: `local-resource-audio-${generatedIndex}`,
+    title,
+    src: generated.audioSrc,
+    mediaType: 'audio',
+    assetKind: generated.audioKind,
+    x: frameX ?? worldCenter.x - width / 2,
+    y: frameY ?? worldCenter.y - height / 2,
+    width,
+    height,
+    originalWidth,
+    originalHeight,
+    zIndex: generatedIndex + 10,
+    sourceType: generated.sourceType,
+    prompt: generated.prompt,
+    actualPrompt: generated.actualPrompt ?? generated.prompt,
+    model: generated.model,
+    provider: generated.provider,
+    taskId: generated.taskId,
+    objectKey: generated.objectKey,
+    assetObjectId: generated.assetObjectId,
+    durationSeconds: generated.durationSeconds ?? undefined,
+    generationInputs,
+  };
+}
+
+export function createCharacterAnimationResultLayer({
+  generated,
+  generatedIndex,
+  title,
+  canvasSize,
+  viewport,
+  generationInputs,
+  frame,
+  sourceLayer,
+}: CharacterAnimationResultLayerOptions): CanvasLayer | null {
+  const previewFrame = generated.frames[0];
+  if (!previewFrame) {
+    return null;
+  }
+  const originalWidth = previewFrame.width || 1024;
+  const originalHeight = previewFrame.height || 1024;
+  const { width, height } = resolveLayerResolutionSize(
+    originalWidth,
+    originalHeight,
+    { width: 420, height: 420 },
+  );
+  const worldCenter = getViewportWorldCenter({ canvasSize, viewport });
+  const frameX =
+    frame && frame.width > 0
+      ? frame.x + frame.width / 2 - width / 2
+      : undefined;
+  const frameY =
+    frame && frame.height > 0
+      ? frame.y + frame.height / 2 - height / 2
+      : undefined;
+
+  return {
+    id: `layer-character-animation-${generatedIndex}`,
+    resourceId: `local-resource-character-animation-${generatedIndex}`,
+    title,
+    src: generated.previewVideoPath,
+    mediaType: 'video',
+    thumbnailSrc: previewFrame.imageSrc,
+    x: frameX ?? worldCenter.x - width / 2,
+    y: frameY ?? worldCenter.y - height / 2,
+    width,
+    height,
+    originalWidth,
+    originalHeight,
+    zIndex: generatedIndex + 10,
+    sourceType: 'generated',
+    prompt: generated.prompt,
+    actualPrompt: generated.prompt,
+    model: generated.model,
+    provider: 'ark',
+    taskId: generated.taskId,
+    assetKind: 'character-animation',
+    durationSeconds: generated.durationSeconds,
+    sourceResourceId: sourceLayer?.resourceId,
+    groupId: sourceLayer?.groupId,
+    generationInputs,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.test.ts b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
new file mode 100644
index 000000000..abe7fa51b
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationModel.test.ts
@@ -0,0 +1,430 @@
+import { describe, expect, it } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  BACKGROUND_MUSIC_MODEL_SUNO,
+  buildCharacterGenerationInputs,
+  buildEditGenerationInputs,
+  buildIconGenerationInputs,
+  buildImageGenerationInputs,
+  buildQuickEditGenerationInputs,
+  buildQuickEditModelOptions,
+  buildSoundEffectGenerationInputs,
+  buildSpecGenerationInputs,
+  buildSpecPrompt,
+  calculateCharacterAnimationPrice,
+  calculateEditorBackgroundMusicPrice,
+  calculateEditorIconSpritesheetPrice,
+  calculateEditorImageGenerationPrice,
+  calculateEditorImageModelPrice,
+  calculateEditorSoundEffectPrice,
+  calculateEditorSpecGenerationPrice,
+  calculateEditorUiDesignPrice,
+  calculateEditorVideoPrice,
+  CHARACTER_ANIMATION_MODEL,
+  DEFAULT_IMAGE_MODEL,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  DEFAULT_VIDEO_MODEL,
+  EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG,
+  EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG,
+  EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG,
+  EDITOR_IMAGE_MODEL_OPTIONS,
+  EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG,
+  EDITOR_SOUND_EFFECT_MODEL_OPTIONS,
+  EDITOR_SPEC_MODEL_MUD_POINT_CONFIG,
+  EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG,
+  EDITOR_VIDEO_MODEL_OPTIONS,
+  getGenerationFrameAriaLabel,
+  getGenerationFrameLabel,
+  IMAGE_MODEL_GPT_IMAGE_2,
+  normalizeQuickEditPromptSourceReference,
+  resolveCharacterAnimationSourceImageSrc,
+  resolveImageGenerationErrorMessage,
+  VIDEO_MODEL_KLING_3,
+  VIDEO_MODEL_KLING_3_OMNI,
+  VIDEO_MODEL_SEEDANCE_2,
+  VIDEO_MODEL_VEO_3_1,
+  VIDEO_MODEL_VEO_3_1_FAST,
+} from './ImageCanvasGenerationModel';
+
+describe('ImageCanvasGenerationModel', () => {
+  it('为所有编辑器生成模型提供显式定价配置', () => {
+    expect(
+      EDITOR_IMAGE_MODEL_OPTIONS.map((option) => option.value).filter(
+        (model) => !(model in EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG),
+      ),
+    ).toEqual([]);
+    expect(
+      EDITOR_VIDEO_MODEL_OPTIONS.map((option) => option.value).filter(
+        (model) => !(model in EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG),
+      ),
+    ).toEqual([]);
+    expect(
+      EDITOR_SOUND_EFFECT_MODEL_OPTIONS.map((option) => option.value).filter(
+        (model) => !(model in EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG),
+      ),
+    ).toEqual([]);
+    expect(EDITOR_SPEC_MODEL_MUD_POINT_CONFIG[IMAGE_MODEL_GPT_IMAGE_2]).toBe(5);
+    expect(
+      EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG[CHARACTER_ANIMATION_MODEL],
+    ).toBeTruthy();
+    expect(
+      EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG[BACKGROUND_MUSIC_MODEL_SUNO],
+    ).toBe(5);
+    // 中文注释：Veo 已从前端入口移除，但客户端类型和后端兼容层仍保留，定价表也必须覆盖，避免旧布局回放或测试请求价格漂移。
+    expect(EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[VIDEO_MODEL_VEO_3_1]).toBeTruthy();
+    expect(
+      EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[VIDEO_MODEL_VEO_3_1_FAST],
+    ).toBeTruthy();
+  });
+
+  it('所有生成按钮价格都从模型定价配置推导', () => {
+    expect(calculateEditorImageModelPrice(DEFAULT_IMAGE_MODEL)).toBe(
+      EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[DEFAULT_IMAGE_MODEL],
+    );
+    expect(calculateEditorImageModelPrice(IMAGE_MODEL_GPT_IMAGE_2)).toBe(20);
+    expect(
+      calculateEditorImageGenerationPrice({
+        kind: 'character',
+        model: IMAGE_MODEL_GPT_IMAGE_2,
+      }),
+    ).toBe(EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[IMAGE_MODEL_GPT_IMAGE_2]);
+    expect(calculateEditorIconSpritesheetPrice(DEFAULT_IMAGE_MODEL)).toBe(
+      EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[DEFAULT_IMAGE_MODEL],
+    );
+    expect(calculateEditorUiDesignPrice(IMAGE_MODEL_GPT_IMAGE_2)).toBe(
+      EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[IMAGE_MODEL_GPT_IMAGE_2],
+    );
+    expect(calculateEditorSpecGenerationPrice(IMAGE_MODEL_GPT_IMAGE_2)).toBe(
+      EDITOR_SPEC_MODEL_MUD_POINT_CONFIG[IMAGE_MODEL_GPT_IMAGE_2],
+    );
+    expect(calculateEditorVideoPrice(DEFAULT_VIDEO_MODEL, '720p', 5)).toBe(
+      EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[DEFAULT_VIDEO_MODEL]['720p'] * 5,
+    );
+    expect(calculateEditorVideoPrice(VIDEO_MODEL_SEEDANCE_2, '480p', 4)).toBe(
+      EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[VIDEO_MODEL_SEEDANCE_2]['480p'] * 4,
+    );
+    expect(calculateEditorVideoPrice(VIDEO_MODEL_KLING_3, '480p', 4)).toBe(
+      EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[VIDEO_MODEL_KLING_3]['480p'] * 4,
+    );
+    expect(calculateEditorVideoPrice(VIDEO_MODEL_KLING_3, '720p', 5)).toBe(
+      150,
+    );
+    expect(calculateEditorVideoPrice(VIDEO_MODEL_KLING_3_OMNI, '720p', 5)).toBe(
+      200,
+    );
+    expect(calculateCharacterAnimationPrice(CHARACTER_ANIMATION_MODEL, '720p', 6))
+      .toBe(
+        EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG[
+          CHARACTER_ANIMATION_MODEL
+        ]['720p'] * 6,
+      );
+    expect(calculateEditorSoundEffectPrice(DEFAULT_SOUND_EFFECT_MODEL)).toBe(
+      EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG[DEFAULT_SOUND_EFFECT_MODEL],
+    );
+    expect(calculateEditorBackgroundMusicPrice(BACKGROUND_MUSIC_MODEL_SUNO)).toBe(
+      EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG[BACKGROUND_MUSIC_MODEL_SUNO],
+    );
+  });
+
+  it('builds user-facing generation input snapshots instead of backend prompts', () => {
+    expect(buildImageGenerationInputs('  一张明亮主视觉  ')).toEqual({
+      fields: [{ title: '生成提示词', value: '一张明亮主视觉' }],
+      references: [],
+    });
+
+    expect(
+      buildSpecGenerationInputs('character', {
+        playSetting: '平台跳跃',
+        artStyle: '像素风',
+        bodyRatio: '3',
+        characterView: '右向三分之二侧身',
+        customPrompt: '',
+      }),
+    ).toEqual({
+      fields: [
+        { title: '玩法设定', value: '平台跳跃' },
+        { title: '美术风格', value: '像素风' },
+        { title: '头身比', value: '3' },
+        { title: '角色视角', value: '右向三分之二侧身' },
+      ],
+      references: [],
+    });
+  });
+
+  it('builds character, icon and edit reference snapshots', () => {
+    const sourceLayer = buildSourceLayer();
+
+    expect(
+      buildCharacterGenerationInputs(
+        '主角骑士',
+        {
+          id: 'spec',
+          label: '角色规范',
+          src: '/spec.png',
+          resourceId: 'resource-spec',
+        },
+        [
+          {
+            id: 'ref-1',
+            label: '盔甲参考',
+            src: '/armor.png',
+            resourceId: 'resource-armor',
+          },
+        ],
+      ),
+    ).toEqual({
+      fields: [{ title: '角色设定', value: '主角骑士' }],
+      references: [
+        {
+          title: '角色规范',
+          label: '角色规范',
+          refType: 'project-resource',
+          refId: 'resource-spec',
+        },
+        {
+          title: '常规参考图 1',
+          label: '盔甲参考',
+          refType: 'project-resource',
+          refId: 'resource-armor',
+        },
+      ],
+    });
+
+    expect(
+      buildIconGenerationInputs(['返回按钮', '设置按钮'], {
+        id: 'icon-spec',
+        label: '图标规范',
+        src: '/icon-spec.png',
+        resourceId: 'resource-icon-spec',
+      }),
+    ).toEqual({
+      fields: [
+        { title: '素材描述', value: '返回按钮\n设置按钮' },
+      ],
+      references: [
+        {
+          title: '图标规范',
+          label: '图标规范',
+          refType: 'project-resource',
+          refId: 'resource-icon-spec',
+        },
+      ],
+    });
+
+    expect(
+      buildEditGenerationInputs('修改要求', '换成夜晚', sourceLayer),
+    ).toEqual({
+      fields: [{ title: '修改要求', value: '换成夜晚' }],
+      references: [
+        {
+          title: '参考图',
+          label: '原图',
+          refType: 'project-resource',
+          refId: 'resource-source',
+        },
+      ],
+    });
+    expect(
+      buildQuickEditGenerationInputs('快速编辑提示词', '让图2下雨', sourceLayer, [
+        {
+          id: 'ref-1',
+          label: '天空',
+          src: '/sky.png',
+          resourceId: 'resource-sky',
+        },
+      ]),
+    ).toEqual({
+      fields: [{ title: '快速编辑提示词', value: '让图2下雨' }],
+      references: [
+        {
+          title: '参考图 1',
+          label: '天空',
+          refType: 'project-resource',
+          refId: 'resource-sky',
+        },
+      ],
+    });
+  });
+
+  it('rewrites quick edit source image references to the final image index', () => {
+    expect(normalizeQuickEditPromptSourceReference('把图1改成夜晚', 3)).toBe(
+      '把图3改成夜晚',
+    );
+    expect(normalizeQuickEditPromptSourceReference('参考原图增加暖光', 2)).toBe(
+      '参考图2增加暖光',
+    );
+    expect(normalizeQuickEditPromptSourceReference('保留图1构图', 1)).toBe(
+      '保留图1构图',
+    );
+    expect(
+      normalizeQuickEditPromptSourceReference('保持当前图片构图', 1),
+    ).toBe('保持图1构图');
+    expect(
+      normalizeQuickEditPromptSourceReference('不要影响图10内容', 2),
+    ).toBe('不要影响图10内容');
+  });
+
+  it('keeps generated prompts and quick edit options stable', () => {
+    const prompt = buildSpecPrompt('ui', {
+      playSetting: '消除玩法',
+      artStyle: '清爽卡通',
+      bodyRatio: '3',
+      characterView: '',
+      customPrompt: '',
+    });
+
+    expect(prompt).toContain('生成一张完整游戏UI规范汇总设定展板');
+    expect(prompt).toContain('玩法设定：消除玩法');
+    expect(buildSpecPrompt('custom', { ...blankSpecValues, customPrompt: '自定义' }))
+      .toBe('自定义');
+    expect(buildQuickEditModelOptions('nano-banana')).toEqual([
+      { label: 'nanobanana2', value: DEFAULT_IMAGE_MODEL },
+      { label: 'gpt-image-2', value: 'gpt-image-2' },
+    ]);
+    expect(buildQuickEditModelOptions('nanobanana2')).toEqual([
+      { label: 'nanobanana2', value: DEFAULT_IMAGE_MODEL },
+      { label: 'gpt-image-2', value: 'gpt-image-2' },
+    ]);
+  });
+
+  it('adds reference image semantics and snapshots for spec generation references', () => {
+    const prompt = buildSpecPrompt(
+      'ui',
+      {
+        playSetting: '消除玩法',
+        artStyle: '清爽卡通',
+        bodyRatio: '3',
+        characterView: '',
+        customPrompt: '',
+      },
+      true,
+    );
+
+    expect(prompt).toContain('参考图生成规范');
+    expect(prompt).toContain('参考图1');
+    expect(prompt).toContain('生成一张完整游戏UI规范汇总设定展板');
+    expect(
+      buildSpecPrompt(
+        'custom',
+        { ...blankSpecValues, customPrompt: '生成一张怪兽规范图' },
+        true,
+      ),
+    ).toContain('生成一张怪兽规范图');
+    expect(
+      buildSpecGenerationInputs(
+        'custom',
+        { ...blankSpecValues, customPrompt: '生成一张怪兽规范图' },
+        {
+          id: 'spec-ref',
+          label: '参考.png',
+          src: '/ref.png',
+          resourceId: 'resource-ref',
+        },
+      ),
+    ).toEqual({
+      fields: [{ title: '自定义规范提示词', value: '生成一张怪兽规范图' }],
+      references: [
+        {
+          title: '参考图',
+          label: '参考.png',
+          refType: 'project-resource',
+          refId: 'resource-ref',
+        },
+      ],
+    });
+  });
+
+  it('uses objectKey for character animation references before falling back to src', () => {
+    expect(
+      resolveCharacterAnimationSourceImageSrc({
+        ...buildSourceLayer(),
+        objectKey: 'generated/character.png',
+      }),
+    ).toBe('generated/character.png');
+    expect(resolveCharacterAnimationSourceImageSrc(buildSourceLayer())).toBe(
+      '/source.png',
+    );
+  });
+
+  it('uses the extracted transparent frame when reusing a playable character animation layer', () => {
+    expect(
+      resolveCharacterAnimationSourceImageSrc({
+        ...buildSourceLayer(),
+        assetKind: 'character-animation',
+        mediaType: 'video',
+        src: '/generated-character-drafts/editor/preview.mp4',
+        thumbnailSrc: '/generated-character-drafts/editor/frame01.png',
+      }),
+    ).toBe('/generated-character-drafts/editor/frame01.png');
+  });
+
+  it('maps generation dialog mode and authorization errors to user-facing copy', () => {
+    const iconDialog: CanvasGenerationDialogState = {
+      id: 'dialog-icon',
+      mode: 'icon',
+      prompt: '',
+      status: 'idle',
+    };
+
+    expect(getGenerationFrameAriaLabel(iconDialog)).toBe('图标素材生成占位图');
+    expect(getGenerationFrameLabel(iconDialog)).toBe('Icon Generator');
+    expect(
+      getGenerationFrameAriaLabel({
+        ...iconDialog,
+        mode: 'quick-edit',
+      }),
+    ).toBe('快速编辑生成占位图');
+    expect(getGenerationFrameLabel({ ...iconDialog, mode: 'quick-edit' })).toBe(
+      'Quick Edit Generator',
+    );
+    expect(
+      buildSoundEffectGenerationInputs('金币掉落叮当声', 'audio1.0', 7),
+    ).toEqual({
+      fields: [
+        { title: 'prompt', value: '金币掉落叮当声' },
+        { title: 'model', value: 'audio1.0' },
+        { title: 'duration', value: '7秒' },
+      ],
+      references: [],
+    });
+    expect(
+      resolveImageGenerationErrorMessage(
+        new ApiClientError({
+          message: '未授权访问（requestId: one）',
+          status: 401,
+          code: 'UNAUTHORIZED',
+        }),
+      ),
+    ).toBe('请先登录后再生成图片');
+  });
+});
+
+const blankSpecValues = {
+  playSetting: '',
+  artStyle: '',
+  bodyRatio: '3',
+  characterView: '',
+  customPrompt: '',
+};
+
+function buildSourceLayer(): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '原图',
+    src: '/source.png',
+    x: 0,
+    y: 0,
+    width: 512,
+    height: 512,
+    originalWidth: 512,
+    originalHeight: 512,
+    zIndex: 1,
+    sourceType: 'uploaded',
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationModel.ts b/src/components/image-editor/ImageCanvasGenerationModel.ts
new file mode 100644
index 000000000..7b4b3b6a8
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationModel.ts
@@ -0,0 +1,1208 @@
+import { ApiClientError } from '../../services/apiClient';
+import type {
+  EditorCharacterAnimationRatio,
+  EditorCharacterAnimationResolution,
+} from '../../services/image-editor/editorProjectClient';
+import { isGeneratedLayer } from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasGenerationInputField,
+  CanvasGenerationInputReference,
+  CanvasGenerationInputs,
+  CanvasLayer,
+  CharacterReferenceImage,
+  GenerateDialogState,
+  PublicationMaterialsGameInfo,
+  PublicationMaterialsWorkflowId,
+  SpecFormValues,
+  SpecGenerationType,
+} from './ImageCanvasEditorTypes';
+import {
+  getPublicationMaterialsWorkflow,
+  type PublicationMaterialsWorkflow,
+} from './ImageCanvasPublicationMaterialsModel';
+
+// 中文注释：与 api-server/src/editor_generation_config.rs 保持同名语义，当前作为前端展示兜底。
+export const EDITOR_GENERATION_MUD_POINT_CONFIG = {
+  image: 12,
+  spec: 5,
+  character: 12,
+  icon: 12,
+  uiDesign: 12,
+  videoPerSecond: {
+    '480p': 10,
+    '720p': 20,
+  },
+  characterAnimationPerSecond: {
+    '480p': 10,
+    '720p': 20,
+  },
+  soundEffect: 10,
+  backgroundMusic: 5,
+} as const;
+export const SPEC_GENERATION_SIZE = '2048x1152';
+export const SPEC_FRAME_ORIGINAL_SIZE = { width: 2048, height: 1152 };
+export const SPEC_FRAME_DISPLAY_SIZE = { width: 560, height: 315 };
+export const CHARACTER_FRAME_ORIGINAL_SIZE = { width: 2048, height: 2048 };
+export const CHARACTER_FRAME_DISPLAY_SIZE = { width: 420, height: 420 };
+export const CHARACTER_ANIMATION_FRAME_ORIGINAL_SIZE = {
+  width: 1024,
+  height: 1024,
+};
+export const CHARACTER_ANIMATION_FRAME_DISPLAY_SIZE = {
+  width: 420,
+  height: 420,
+};
+export const ICON_FRAME_ORIGINAL_SIZE = { width: 512, height: 512 };
+export const ICON_FRAME_DISPLAY_SIZE = { width: 360, height: 360 };
+export const UI_DESIGN_FRAME_ORIGINAL_SIZE = { width: 2048, height: 1152 };
+export const UI_DESIGN_FRAME_DISPLAY_SIZE = { width: 560, height: 315 };
+export const PUBLICATION_FRAME_ORIGINAL_SIZE: Record<
+  PublicationMaterialsWorkflowId,
+  { width: number; height: number }
+> = {
+  'publication-cover-image': { width: 720, height: 540 },
+  'publication-detail-gallery': { width: 720, height: 1280 },
+  'publication-promo-poster': { width: 1280, height: 720 },
+};
+export const PUBLICATION_FRAME_DISPLAY_SIZE: Record<
+  PublicationMaterialsWorkflowId,
+  { width: number; height: number }
+> = {
+  'publication-cover-image': { width: 480, height: 360 },
+  'publication-detail-gallery': { width: 360, height: 640 },
+  'publication-promo-poster': { width: 560, height: 315 },
+};
+export const IMAGE_MODEL_GPT_IMAGE_2 = 'gpt-image-2';
+export const IMAGE_MODEL_NANOBANANA2 = 'gemini-3.1-flash-image-preview';
+export const DEFAULT_IMAGE_MODEL = IMAGE_MODEL_NANOBANANA2;
+const IMAGE_MODEL_NANOBANANA_ALIASES = new Set([
+  IMAGE_MODEL_NANOBANANA2,
+  'nanobanana2',
+  'nano-banana',
+]);
+export const SPEC_GENERATION_MODEL = IMAGE_MODEL_GPT_IMAGE_2;
+export const EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG = {
+  [IMAGE_MODEL_NANOBANANA2]: EDITOR_GENERATION_MUD_POINT_CONFIG.image,
+  // 中文注释：gpt-image-2 作为更高成本图片模型独立计费，避免切换模型后按钮价格不变。
+  [IMAGE_MODEL_GPT_IMAGE_2]: 20,
+} as const;
+export const EDITOR_SPEC_MODEL_MUD_POINT_CONFIG = {
+  [IMAGE_MODEL_GPT_IMAGE_2]: EDITOR_GENERATION_MUD_POINT_CONFIG.spec,
+} as const;
+export const SPEC_GENERATION_COST =
+  EDITOR_SPEC_MODEL_MUD_POINT_CONFIG[SPEC_GENERATION_MODEL];
+export const SPEC_GENERATION_ASPECT_RATIO = '16:9';
+export const SPEC_GENERATION_IMAGE_SIZE = '2K';
+export const ICON_DESCRIPTION_LIMIT = 100;
+export const DEFAULT_PUBLICATION_GAME_INFO: PublicationMaterialsGameInfo = {
+  gameName: '',
+  gameCategories: '',
+  gameDescription: '',
+};
+export const DEFAULT_ICON_DESCRIPTIONS = [
+  '返回按钮',
+  '设置按钮',
+  '下一关按钮',
+  '提示按钮',
+  '原图按钮',
+  '冻结按钮',
+];
+export const UI_DESIGN_ASSET_EXTRACTION_PROMPT =
+  '提取画面中的所有独立并整理成spritesheet';
+export const QUICK_EDIT_SIZE_PRESETS = [
+  '1024x1024',
+  '1536x1024',
+  '2048x1152',
+  '1024x1536',
+] as const;
+export const QUICK_EDIT_MODEL_OPTIONS = [
+  { label: 'nanobanana2', value: IMAGE_MODEL_NANOBANANA2 },
+  { label: 'gpt-image-2', value: IMAGE_MODEL_GPT_IMAGE_2 },
+] as const;
+export const EDITOR_IMAGE_MODEL_OPTIONS = QUICK_EDIT_MODEL_OPTIONS;
+export const EDITOR_IMAGE_DIMENSION_OPTIONS = {
+  [IMAGE_MODEL_NANOBANANA2]: {
+    aspectRatios: ['1:1', '4:3', '3:2', '2:3', '9:16', '16:9'],
+    imageSizes: ['0.5K', '1K', '2K'],
+  },
+  [IMAGE_MODEL_GPT_IMAGE_2]: {
+    aspectRatios: ['1:1', '4:3', '3:2', '2:3', '9:16', '16:9'],
+    imageSizes: ['1K', '2K'],
+  },
+} as const;
+
+type EditorImageFrameSize = {
+  width: number;
+  height: number;
+};
+
+function getSafeImageSizeValue(imageSize: string | null | undefined) {
+  return (imageSize ?? '1K').trim().toUpperCase();
+}
+
+function getImageSizeLongEdge(imageSize: string | null | undefined) {
+  const normalizedImageSize = getSafeImageSizeValue(imageSize);
+  if (normalizedImageSize === '0.5K') {
+    return 512;
+  }
+  if (normalizedImageSize === '2K') {
+    return 2048;
+  }
+  return 1024;
+}
+
+function resolveAspectRatioNumbers(aspectRatio: string | null | undefined) {
+  const [rawWidth = 1, rawHeight = 1] = (aspectRatio ?? '1:1')
+    .split(':')
+    .map((value) => Number(value));
+  const width = Number.isFinite(rawWidth) && rawWidth > 0 ? rawWidth : 1;
+  const height = Number.isFinite(rawHeight) && rawHeight > 0 ? rawHeight : 1;
+  return { width, height };
+}
+
+function resolveImageFrameSizeFromRatio({
+  aspectRatio,
+  imageSize,
+}: {
+  aspectRatio: string | null | undefined;
+  imageSize: string | null | undefined;
+}): EditorImageFrameSize {
+  const longEdge = getImageSizeLongEdge(imageSize);
+  const ratio = resolveAspectRatioNumbers(aspectRatio);
+  if (ratio.width >= ratio.height) {
+    return {
+      width: longEdge,
+      height: Math.max(1, Math.round((longEdge * ratio.height) / ratio.width)),
+    };
+  }
+  return {
+    width: Math.max(1, Math.round((longEdge * ratio.width) / ratio.height)),
+    height: longEdge,
+  };
+}
+
+export function resolveEditorImageGenerationPixelSize({
+  aspectRatio,
+  imageSize,
+}: {
+  model: string | null | undefined;
+  aspectRatio: string | null | undefined;
+  imageSize: string | null | undefined;
+}): EditorImageFrameSize {
+  return resolveImageFrameSizeFromRatio({ aspectRatio, imageSize });
+}
+
+export function resolveEditorImageSizeLabel({
+  aspectRatio,
+  imageSize,
+}: {
+  aspectRatio: string | null | undefined;
+  imageSize: string | null | undefined;
+}) {
+  return `${aspectRatio?.trim() || '1:1'}·${getSafeImageSizeValue(imageSize)}`;
+}
+
+export function inferEditorImageAspectRatio(width: number, height: number) {
+  const safeWidth = Number.isFinite(width) && width > 0 ? Math.round(width) : 1;
+  const safeHeight =
+    Number.isFinite(height) && height > 0 ? Math.round(height) : 1;
+  const commonRatios = EDITOR_IMAGE_DIMENSION_OPTIONS[
+    IMAGE_MODEL_NANOBANANA2
+  ].aspectRatios as readonly string[];
+  const sourceRatio = safeWidth / safeHeight;
+  return commonRatios.reduce((bestRatio, ratio) => {
+    const bestNumbers = resolveAspectRatioNumbers(bestRatio);
+    const ratioNumbers = resolveAspectRatioNumbers(ratio);
+    const bestDiff = Math.abs(bestNumbers.width / bestNumbers.height - sourceRatio);
+    const ratioDiff = Math.abs(ratioNumbers.width / ratioNumbers.height - sourceRatio);
+    return ratioDiff < bestDiff ? ratio : bestRatio;
+  }, commonRatios[0] ?? '1:1');
+}
+
+export function inferEditorImageSizeLabel(width: number, height: number) {
+  const longEdge = Math.max(width, height);
+  if (longEdge <= 768) {
+    return '0.5K';
+  }
+  if (longEdge > 1536) {
+    return '2K';
+  }
+  return '1K';
+}
+
+export function resizeGenerationPlaceholderToImageSelection(
+  dialog: GenerateDialogState,
+): GenerateDialogState {
+  if (!dialog.placeholder) {
+    return dialog;
+  }
+  const size = resolveEditorImageGenerationPixelSize({
+    model: dialog.imageModel,
+    aspectRatio: dialog.aspectRatio,
+    imageSize: dialog.imageSize,
+  });
+  const centerX = dialog.placeholder.x + dialog.placeholder.width / 2;
+  const centerY = dialog.placeholder.y + dialog.placeholder.height / 2;
+  return {
+    ...dialog,
+    placeholder: {
+      ...dialog.placeholder,
+      x: centerX - size.width / 2,
+      y: centerY - size.height / 2,
+      width: size.width,
+      height: size.height,
+      originalWidth: size.width,
+      originalHeight: size.height,
+    },
+  };
+}
+
+function resolveEvenVideoWidth(height: number, aspectRatio: string | null | undefined) {
+  const ratio = resolveAspectRatioNumbers(aspectRatio ?? '16:9');
+  const rawWidth = Math.max(1, Math.round((height * ratio.width) / ratio.height));
+  return rawWidth % 2 === 0 ? rawWidth : rawWidth + 1;
+}
+
+export function resolveEditorVideoGenerationPixelSize({
+  aspectRatio,
+  resolution,
+}: {
+  aspectRatio: string | null | undefined;
+  resolution: '480p' | '720p' | '1080p' | string | null | undefined;
+}): EditorImageFrameSize {
+  const height =
+    resolution === '1080p' ? 1080 : resolution === '720p' ? 720 : 480;
+  return {
+    width: resolveEvenVideoWidth(height, aspectRatio),
+    height,
+  };
+}
+
+export function resizeGenerationPlaceholderToVideoSelection(
+  dialog: GenerateDialogState,
+): GenerateDialogState {
+  if (!dialog.placeholder) {
+    return dialog;
+  }
+  const size = resolveEditorVideoGenerationPixelSize({
+    aspectRatio: dialog.videoAspectRatio,
+    resolution: dialog.videoResolution,
+  });
+  const centerX = dialog.placeholder.x + dialog.placeholder.width / 2;
+  const centerY = dialog.placeholder.y + dialog.placeholder.height / 2;
+  return {
+    ...dialog,
+    placeholder: {
+      ...dialog.placeholder,
+      x: centerX - size.width / 2,
+      y: centerY - size.height / 2,
+      width: size.width,
+      height: size.height,
+      originalWidth: size.width,
+      originalHeight: size.height,
+    },
+  };
+}
+export const VIDEO_MODEL_SEEDANCE_2 = 'seedance2.0';
+export const VIDEO_MODEL_SEEDANCE_2_FAST = 'seedance2.0-fast';
+export const VIDEO_MODEL_KLING_3 = 'kling3.0';
+export const VIDEO_MODEL_KLING_3_OMNI = 'kling3.0-omni';
+export const VIDEO_MODEL_VEO_3_1 = 'veo3.1';
+export const VIDEO_MODEL_VEO_3_1_FAST = 'veo3.1-fast';
+export const DEFAULT_VIDEO_MODEL = VIDEO_MODEL_SEEDANCE_2_FAST;
+export const CHARACTER_ANIMATION_MODEL = VIDEO_MODEL_SEEDANCE_2_FAST;
+export const SOUND_EFFECT_MODEL_VIDU = 'audio1.0';
+export const DEFAULT_SOUND_EFFECT_MODEL = SOUND_EFFECT_MODEL_VIDU;
+export const DEFAULT_SOUND_EFFECT_DURATION_SECONDS = 5;
+export const SOUND_EFFECT_DURATION_OPTIONS = Array.from(
+  { length: 9 },
+  (_, index) => index + 2,
+);
+export const BACKGROUND_MUSIC_MODEL_SUNO = 'chirp-v5';
+export const DEFAULT_BACKGROUND_MUSIC_MODEL = BACKGROUND_MUSIC_MODEL_SUNO;
+const EDITOR_VIDEO_RESOLUTION_RATE_CONFIG = {
+  '480p': EDITOR_GENERATION_MUD_POINT_CONFIG.videoPerSecond['480p'],
+  '720p': EDITOR_GENERATION_MUD_POINT_CONFIG.videoPerSecond['720p'],
+  '1080p': EDITOR_GENERATION_MUD_POINT_CONFIG.videoPerSecond['720p'] * 2,
+} as const;
+const EDITOR_VIDEO_STANDARD_RESOLUTION_RATE_CONFIG = {
+  '480p': 12,
+  '720p': 24,
+  '1080p': 48,
+} as const;
+const EDITOR_VIDEO_KLING_RESOLUTION_RATE_CONFIG = {
+  '480p': 15,
+  '720p': 30,
+  '1080p': 60,
+} as const;
+const EDITOR_VIDEO_KLING_OMNI_RESOLUTION_RATE_CONFIG = {
+  '480p': 20,
+  '720p': 40,
+  '1080p': 80,
+} as const;
+export const EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG = {
+  [VIDEO_MODEL_SEEDANCE_2_FAST]: EDITOR_VIDEO_RESOLUTION_RATE_CONFIG,
+  [VIDEO_MODEL_SEEDANCE_2]: EDITOR_VIDEO_STANDARD_RESOLUTION_RATE_CONFIG,
+  [VIDEO_MODEL_KLING_3]: EDITOR_VIDEO_KLING_RESOLUTION_RATE_CONFIG,
+  [VIDEO_MODEL_KLING_3_OMNI]: EDITOR_VIDEO_KLING_OMNI_RESOLUTION_RATE_CONFIG,
+  // 中文注释：前端不展示 Veo 入口，但类型与后端兼容层仍可接收旧布局回放，定价表必须同步覆盖。
+  [VIDEO_MODEL_VEO_3_1]: EDITOR_VIDEO_RESOLUTION_RATE_CONFIG,
+  [VIDEO_MODEL_VEO_3_1_FAST]: EDITOR_VIDEO_RESOLUTION_RATE_CONFIG,
+} as const;
+export const EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG = {
+  [CHARACTER_ANIMATION_MODEL]: {
+    '480p': EDITOR_GENERATION_MUD_POINT_CONFIG.characterAnimationPerSecond['480p'],
+    '720p': EDITOR_GENERATION_MUD_POINT_CONFIG.characterAnimationPerSecond['720p'],
+  },
+} as const;
+export const EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG = {
+  [SOUND_EFFECT_MODEL_VIDU]: EDITOR_GENERATION_MUD_POINT_CONFIG.soundEffect,
+} as const;
+export const EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG = {
+  [BACKGROUND_MUSIC_MODEL_SUNO]: EDITOR_GENERATION_MUD_POINT_CONFIG.backgroundMusic,
+} as const;
+export const EDITOR_SOUND_EFFECT_MODEL_OPTIONS = [
+  { label: 'Vidu', value: SOUND_EFFECT_MODEL_VIDU },
+] as const;
+export const SEEDANCE_VIDEO_REFERENCE_LIMITS = {
+  image: 9,
+  video: 3,
+  audio: 3,
+  requestBytes: 64 * 1024 * 1024,
+} as const;
+export const QUICK_EDIT_REFERENCE_LIMIT = 8;
+export const CHARACTER_ANIMATION_ACTION_PROMPTS = [
+  { label: '待机', text: '待机动作，轻微呼吸起伏。' },
+  { label: '行走', text: '循环行走动作，步伐稳定。' },
+  { label: '奔跑', text: '循环奔跑动作，动作清晰有力。' },
+  { label: '跳跃', text: '起跳、滞空、落地动作。' },
+  { label: '攻击', text: '攻击动作，前摇、出手、收招清晰。' },
+  { label: '受击', text: '受击后短暂后仰并恢复站姿。' },
+  { label: '倒下', text: '倒下动作，重心下落自然。' },
+] as const;
+export const CHARACTER_ANIMATION_RATIO_OPTIONS: Array<{
+  label: string;
+  value: EditorCharacterAnimationRatio;
+}> = [
+  { label: '与角色图片保持同尺寸', value: 'same' },
+  { label: '1:1', value: '1:1' },
+  { label: '4:3', value: '4:3' },
+  { label: '16:9', value: '16:9' },
+  { label: '9:16', value: '9:16' },
+  { label: '3:4', value: '3:4' },
+];
+export const CHARACTER_ANIMATION_DURATION_OPTIONS = [
+  { label: '32帧·4秒', frameCount: 32, durationSeconds: 4 },
+  { label: '40帧·5秒', frameCount: 40, durationSeconds: 5 },
+  { label: '48帧·6秒', frameCount: 48, durationSeconds: 6 },
+] as const;
+export const VIDEO_FRAME_ORIGINAL_SIZE = { width: 854, height: 480 };
+export const VIDEO_FRAME_DISPLAY_SIZE = { width: 854, height: 480 };
+export const AUDIO_FRAME_ORIGINAL_SIZE = { width: 420, height: 120 };
+export const AUDIO_FRAME_DISPLAY_SIZE = { width: 420, height: 120 };
+export const EDITOR_VIDEO_MODEL_OPTIONS = [
+  { label: 'Seedance 2.0 Fast', value: VIDEO_MODEL_SEEDANCE_2_FAST },
+  { label: 'Seedance 2.0', value: VIDEO_MODEL_SEEDANCE_2 },
+  { label: 'Kling 3.0', value: VIDEO_MODEL_KLING_3 },
+  { label: 'Kling 3.0 Omni', value: VIDEO_MODEL_KLING_3_OMNI },
+] as const;
+export const EDITOR_VIDEO_DURATION_OPTIONS = [
+  4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
+] as const;
+export const EDITOR_VIDEO_ASPECT_RATIO_OPTIONS = [
+  '16:9',
+  '9:16',
+  '1:1',
+  '4:3',
+  '3:4',
+  '21:9',
+] as const;
+export const EDITOR_VIDEO_RESOLUTION_OPTIONS = ['480p', '720p', '1080p'] as const;
+export const DEFAULT_VIDEO_ASPECT_RATIO = '16:9';
+export const DEFAULT_VIDEO_DURATION_SECONDS = 4;
+export const DEFAULT_VIDEO_SOUND = 'on';
+export const DEFAULT_VIDEO_WEB_SEARCH_ENABLED = true;
+
+export const DEFAULT_SPEC_FORM_VALUES: Record<
+  SpecGenerationType,
+  SpecFormValues
+> = {
+  character: {
+    playSetting: '战棋类RPG玩法',
+    artStyle: '像素风',
+    bodyRatio: '3',
+    characterView:
+      '右向斜侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯右视图，也禁止生成正面立绘。',
+    customPrompt: '',
+  },
+  ui: {
+    playSetting: '抓娃娃题材的抓大鹅玩法',
+    artStyle: '毛茸茸',
+    bodyRatio: '3',
+    characterView:
+      '右向斜侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯右视图，也禁止生成正面立绘。',
+    customPrompt: '',
+  },
+  icon: {
+    playSetting: '休闲小游戏',
+    artStyle: '清爽卡通',
+    bodyRatio: '3',
+    characterView:
+      '右向斜侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯右视图，也禁止生成正面立绘。',
+    customPrompt: '',
+  },
+  custom: {
+    playSetting: '',
+    artStyle: '',
+    bodyRatio: '3',
+    characterView:
+      '右向斜侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯右视图，也禁止生成正面立绘。',
+    customPrompt: '',
+  },
+};
+
+export const SPEC_TYPE_LABEL: Record<SpecGenerationType, string> = {
+  character: '角色规范',
+  ui: '图标规范',
+  icon: '图标规范',
+  custom: '自定义规范',
+};
+
+export const CHARACTER_SPEC_VIEW_OPTIONS = [
+  DEFAULT_SPEC_FORM_VALUES.character.characterView,
+  '左向三分之二侧身站姿',
+  '左向三分之二侧身站姿，保留少量正面信息，能读到面部轮廓与胸肩结构，禁止生成完全 90 度纯左视图，也禁止生成正面立绘。',
+  '右向三分之二侧身站姿，保留少量正面信息，强调面部轮廓、胸肩结构与主要装备层次。',
+  '背向斜侧身站姿，保留少量侧脸信息，突出背部服饰层次、武器挂载与轮廓识别。',
+];
+
+export function buildQuickEditSizeOptions(currentSize: string) {
+  return Array.from(new Set([currentSize, ...QUICK_EDIT_SIZE_PRESETS]));
+}
+
+export function normalizeEditorImageModel(
+  model: string | null | undefined,
+) {
+  const normalizedModel = model?.trim();
+  if (!normalizedModel) {
+    return DEFAULT_IMAGE_MODEL;
+  }
+  if (IMAGE_MODEL_NANOBANANA_ALIASES.has(normalizedModel)) {
+    return IMAGE_MODEL_NANOBANANA2;
+  }
+  return normalizedModel;
+}
+
+export function getEditorImageModelDisplayName(
+  model: string | null | undefined,
+) {
+  const normalizedModel = normalizeEditorImageModel(model);
+  return (
+    EDITOR_IMAGE_MODEL_OPTIONS.find((option) => option.value === normalizedModel)
+      ?.label ?? normalizedModel
+  );
+}
+
+export function buildQuickEditModelOptions(currentModel: string) {
+  const normalizedCurrentModel = normalizeEditorImageModel(currentModel);
+  const options = [...QUICK_EDIT_MODEL_OPTIONS];
+  return options.some((option) => option.value === normalizedCurrentModel)
+    ? options
+    : [{ label: normalizedCurrentModel, value: normalizedCurrentModel }, ...options];
+}
+
+export function buildCharacterSpecPrompt(values: SpecFormValues) {
+  return [
+    '生成2D 角色美术视觉规范设定图，纯白底板，整齐排布全身标准立绘；固定统一头身比例、勾线粗细恒定；展示待机行走攻击基础动作帧样例，重心对齐不变位，服饰配饰分层结构示意，搭配专属角色色卡标注色号，无多余杂物，精准尺寸标注，高清矢量规范稿',
+    '禁止模糊、笔触杂乱、光影方向混乱、比例畸形、3D 渲染、实景照片、水印、花纹堆砌、画面抖动错位效果、噪点，',
+    `玩法设计：${values.playSetting.trim() || DEFAULT_SPEC_FORM_VALUES.character.playSetting}`,
+    `美术风格：${values.artStyle.trim() || DEFAULT_SPEC_FORM_VALUES.character.artStyle}`,
+    `头身比：${values.bodyRatio.trim() || DEFAULT_SPEC_FORM_VALUES.character.bodyRatio}`,
+    `视角要求：${values.characterView.trim() || DEFAULT_SPEC_FORM_VALUES.character.characterView}`,
+  ].join('\n');
+}
+
+export function buildUiSpecPrompt(values: SpecFormValues) {
+  return [
+    '生成一张完整游戏UI规范汇总设定展板，纯白色干净背景，Figma专业设计稿质感，矢量锐利线条，页面划分九大区域：色彩规范、字体规范、图标规范、按钮规范、组件规范、布局规范、特效规范、IP规范、主视觉。主视觉居中较大显示，其他八个区域环绕主视觉',
+    '',
+    `玩法设定：${values.playSetting.trim() || DEFAULT_SPEC_FORM_VALUES.ui.playSetting}`,
+    `美术风格：${values.artStyle.trim() || DEFAULT_SPEC_FORM_VALUES.ui.artStyle}`,
+  ].join('\n');
+}
+
+export function buildIconSpecPrompt(values: SpecFormValues) {
+  return [
+    '生成一张游戏图标素材视觉规范展板，纯白色干净背景，展示按钮图标的统一视角、线条粗细、填充风格、描边、阴影、圆角、材质、状态层级和色彩规范，图标样例需要成组排列且风格高度统一。',
+    '',
+    `玩法设定：${values.playSetting.trim() || DEFAULT_SPEC_FORM_VALUES.icon.playSetting}`,
+    `美术风格：${values.artStyle.trim() || DEFAULT_SPEC_FORM_VALUES.icon.artStyle}`,
+  ].join('\n');
+}
+
+export function buildSpecPrompt(
+  type: SpecGenerationType,
+  values: SpecFormValues,
+  hasReferenceImage = false,
+) {
+  const prompt =
+    type === 'character'
+      ? buildCharacterSpecPrompt(values)
+      : type === 'ui'
+        ? buildUiSpecPrompt(values)
+        : type === 'icon'
+          ? buildIconSpecPrompt(values)
+          : values.customPrompt.trim();
+  if (!hasReferenceImage) {
+    return prompt;
+  }
+  return [
+    '参考图生成规范：严格参考图1的构图、风格、材质、色彩、形状语言和视觉层级生成本次规范图；参考图只作为美术方向和规范语义依据，不要直接复制参考图中的文字、水印或无关背景。',
+    prompt,
+  ].join('\n');
+}
+
+export function getLayerKindLabel(layer: CanvasLayer) {
+  if (layer.assetKind === 'spec') {
+    return '规范';
+  }
+  if (layer.assetKind === 'character') {
+    return '角色';
+  }
+  if (layer.assetKind === 'character-animation') {
+    return '动作';
+  }
+  if (layer.assetKind === 'icon') {
+    return '图标';
+  }
+  if (layer.assetKind === 'icon-spritesheet') {
+    return '图集';
+  }
+  if (layer.assetKind === 'icon-spec') {
+    return '图标规范';
+  }
+  if (layer.assetKind === 'publication-material') {
+    return '宣发素材';
+  }
+  if (layer.assetKind === 'ui-design') {
+    return 'UI设计';
+  }
+  if (layer.assetKind === 'video' || layer.mediaType === 'video') {
+    return '视频';
+  }
+  if (layer.assetKind === 'sound-effect') {
+    return '音效';
+  }
+  if (layer.assetKind === 'background-music') {
+    return '背景音乐';
+  }
+  if (layer.mediaType === 'audio') {
+    return '音频';
+  }
+  return null;
+}
+
+export function buildCharacterAnimationGenerationInputs(
+  promptText: string,
+  sourceLayer: CanvasLayer,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField('动作描述', promptText),
+    references: createLayerGenerationInputReference('角色图片', sourceLayer),
+  };
+}
+
+export function formatLayerImageType(layer: CanvasLayer) {
+  if (layer.assetKind === 'spec') {
+    return '规范图片';
+  }
+  if (layer.assetKind === 'character') {
+    return '角色图片';
+  }
+  if (layer.assetKind === 'character-animation') {
+    return '角色动作视频';
+  }
+  if (layer.assetKind === 'icon') {
+    return '图标素材图片';
+  }
+  if (layer.assetKind === 'icon-spritesheet') {
+    return '图标素材图集';
+  }
+  if (layer.assetKind === 'icon-spec') {
+    return '图标规范图片';
+  }
+  if (layer.assetKind === 'publication-material') {
+    return '宣发素材图片';
+  }
+  if (layer.assetKind === 'ui-design') {
+    return 'UI设计图';
+  }
+  if (layer.assetKind === 'video' || layer.mediaType === 'video') {
+    return '生成视频';
+  }
+  if (layer.assetKind === 'sound-effect') {
+    return '游戏音效';
+  }
+  if (layer.assetKind === 'background-music') {
+    return '游戏背景音乐';
+  }
+  if (layer.mediaType === 'audio') {
+    return '生成音频';
+  }
+  return isGeneratedLayer(layer) ? '生成图片' : '上传图片';
+}
+
+export function calculateCharacterAnimationPrice(
+  model: string | null | undefined,
+  resolution: EditorCharacterAnimationResolution,
+  durationSeconds: number,
+) {
+  const normalizedModel = (model ?? CHARACTER_ANIMATION_MODEL).trim();
+  const modelRates =
+    EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG
+    ] ?? EDITOR_CHARACTER_ANIMATION_MODEL_MUD_POINT_CONFIG[CHARACTER_ANIMATION_MODEL];
+  return modelRates[resolution] * durationSeconds;
+}
+
+export function calculateEditorVideoPrice(
+  model: string | null | undefined,
+  resolution: '480p' | '720p' | '1080p',
+  durationSeconds: number,
+) {
+  const normalizedModel = (model ?? DEFAULT_VIDEO_MODEL).trim();
+  const modelRates =
+    EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG
+    ] ?? EDITOR_VIDEO_MODEL_MUD_POINT_CONFIG[DEFAULT_VIDEO_MODEL];
+  return modelRates[resolution] * durationSeconds;
+}
+
+export function calculateEditorImageModelPrice(
+  model: string | null | undefined,
+) {
+  const normalizedModel = normalizeEditorImageModel(model);
+  return (
+    EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_IMAGE_MODEL_MUD_POINT_CONFIG
+    ] ?? EDITOR_GENERATION_MUD_POINT_CONFIG.image
+  );
+}
+
+export function calculateEditorSpecGenerationPrice(
+  model: string | null | undefined = SPEC_GENERATION_MODEL,
+) {
+  const normalizedModel = (model ?? SPEC_GENERATION_MODEL).trim();
+  return (
+    EDITOR_SPEC_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_SPEC_MODEL_MUD_POINT_CONFIG
+    ] ?? EDITOR_SPEC_MODEL_MUD_POINT_CONFIG[SPEC_GENERATION_MODEL]
+  );
+}
+
+export function calculateEditorImageGenerationPrice({
+  kind,
+  model,
+}: {
+  kind?: string | null;
+  model?: string | null;
+} = {}) {
+  const normalizedKind = kind?.trim();
+  if (normalizedKind === 'spec') {
+    return calculateEditorSpecGenerationPrice(model);
+  }
+  return calculateEditorImageModelPrice(model);
+}
+
+export function calculateEditorIconSpritesheetPrice(
+  model: string | null | undefined,
+) {
+  return calculateEditorImageModelPrice(model);
+}
+
+export function calculateEditorUiDesignPrice(
+  model: string | null | undefined,
+) {
+  return calculateEditorImageModelPrice(model);
+}
+
+export function calculateEditorSoundEffectPrice(
+  model: string | null | undefined,
+) {
+  const normalizedModel = (model ?? DEFAULT_SOUND_EFFECT_MODEL).trim();
+  return (
+    EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG
+    ] ?? EDITOR_SOUND_EFFECT_MODEL_MUD_POINT_CONFIG[DEFAULT_SOUND_EFFECT_MODEL]
+  );
+}
+
+export function calculateEditorBackgroundMusicPrice(
+  model: string | null | undefined = DEFAULT_BACKGROUND_MUSIC_MODEL,
+) {
+  const normalizedModel = (model ?? DEFAULT_BACKGROUND_MUSIC_MODEL).trim();
+  return (
+    EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG[
+      normalizedModel as keyof typeof EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG
+    ] ??
+    EDITOR_BACKGROUND_MUSIC_MODEL_MUD_POINT_CONFIG[
+      DEFAULT_BACKGROUND_MUSIC_MODEL
+    ]
+  );
+}
+
+export function resolveCharacterAnimationSourceImageSrc(layer: CanvasLayer) {
+  if (layer.assetKind === 'character-animation' && layer.thumbnailSrc?.trim()) {
+    return layer.thumbnailSrc.trim();
+  }
+  // 中文注释：角色图已持久化到 OSS 时优先传 objectKey，避免把大 Data URL 塞进 JSON 请求体触发 body limit。
+  return layer.objectKey?.trim() || layer.src;
+}
+
+export function createCanvasLayerReference(
+  layer: CanvasLayer,
+): CharacterReferenceImage {
+  const mediaType = layer.mediaType === 'video' || layer.mediaType === 'audio'
+    ? layer.mediaType
+    : undefined;
+  return {
+    id: `canvas-${layer.id}`,
+    label: layer.title,
+    src: layer.objectKey?.trim() || layer.src,
+    ...(mediaType ? { mediaType } : {}),
+    objectKey: layer.objectKey ?? undefined,
+    assetObjectId: layer.assetObjectId ?? undefined,
+    resourceId: layer.resourceId,
+    sourceAssetId: layer.sourceAssetId ?? undefined,
+  };
+}
+
+export function createGenerationInputReference(
+  title: string,
+  reference: Pick<
+    CharacterReferenceImage,
+    'label' | 'resourceId' | 'sourceAssetId'
+  >,
+): CanvasGenerationInputReference[] {
+  const resourceId = reference.resourceId?.trim();
+  if (
+    resourceId &&
+    !resourceId.startsWith('local-') &&
+    !resourceId.startsWith('generation-dialog:')
+  ) {
+    return [
+      {
+        title,
+        label: reference.label,
+        refType: 'project-resource',
+        refId: resourceId,
+      },
+    ];
+  }
+  const sourceAssetId = reference.sourceAssetId?.trim();
+  return sourceAssetId && !sourceAssetId.startsWith('upload-')
+    ? [
+        {
+          title,
+          label: reference.label,
+          refType: 'asset',
+          refId: sourceAssetId,
+        },
+      ]
+    : [];
+}
+
+export function createLayerGenerationInputReference(
+  title: string,
+  layer: CanvasLayer,
+): CanvasGenerationInputReference[] {
+  return createGenerationInputReference(title, {
+    label: layer.title,
+    resourceId: layer.resourceId,
+    sourceAssetId: layer.sourceAssetId,
+  });
+}
+
+export function appendLimitedQuickEditReferences(
+  references: CharacterReferenceImage[] | undefined,
+  nextReferences: CharacterReferenceImage[],
+) {
+  const imageReferences = nextReferences.filter(
+    (reference) => (reference.mediaType ?? 'image') === 'image',
+  );
+  return [
+    ...(references ?? []),
+    ...imageReferences,
+  ].slice(0, QUICK_EDIT_REFERENCE_LIMIT);
+}
+
+export function normalizeQuickEditPromptSourceReference(
+  prompt: string,
+  sourceReferenceIndex: number,
+) {
+  const normalizedIndex = Math.max(1, sourceReferenceIndex);
+  const sourceReferenceLabel = `图${normalizedIndex}`;
+  return prompt
+    .replace(/原图|当前图片|当前图/gu, sourceReferenceLabel)
+    .replace(/图\s*1(?!\d)/gu, sourceReferenceLabel);
+}
+
+export function createGenerationInputField(
+  title: string,
+  value: string | null | undefined,
+): CanvasGenerationInputField[] {
+  const normalizedValue = value?.trim();
+  return normalizedValue ? [{ title, value: normalizedValue }] : [];
+}
+
+export function buildImageGenerationInputs(
+  prompt: string,
+  references?: CharacterReferenceImage[],
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField('生成提示词', prompt),
+    references: (references ?? []).flatMap((reference, index) =>
+      createGenerationInputReference(`参考图 ${index + 1}`, reference),
+    ),
+  };
+}
+
+export function buildVideoGenerationInputs(
+  prompt: string,
+  references?: CharacterReferenceImage[],
+): CanvasGenerationInputs {
+  const mediaIndexes = {
+    image: 0,
+    video: 0,
+    audio: 0,
+  };
+  return {
+    fields: createGenerationInputField('视频描述', prompt),
+    references: (references ?? []).flatMap((reference) => {
+      const mediaType = reference.mediaType ?? 'image';
+      mediaIndexes[mediaType] += 1;
+      const title =
+        mediaType === 'video'
+          ? `参考视频 ${mediaIndexes.video}`
+          : mediaType === 'audio'
+            ? `参考音频 ${mediaIndexes.audio}`
+            : `参考图 ${mediaIndexes.image}`;
+      return createGenerationInputReference(title, reference);
+    }),
+  };
+}
+
+export function buildSoundEffectGenerationInputs(
+  prompt: string,
+  model: string,
+  duration: number,
+): CanvasGenerationInputs {
+  return {
+    fields: [
+      ...createGenerationInputField('prompt', prompt),
+      ...createGenerationInputField('model', model),
+      ...createGenerationInputField('duration', `${duration}秒`),
+    ],
+    references: [],
+  };
+}
+
+export function buildBackgroundMusicGenerationInputs(
+  gptDescriptionPrompt: string,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField(
+      'gpt_description_prompt',
+      gptDescriptionPrompt,
+    ),
+    references: [],
+  };
+}
+
+export function buildSpecGenerationInputs(
+  specType: SpecGenerationType,
+  values: SpecFormValues,
+  reference?: CharacterReferenceImage | null,
+): CanvasGenerationInputs {
+  const references = reference
+    ? createGenerationInputReference('参考图', reference)
+    : [];
+  if (specType === 'custom') {
+    return {
+      fields: createGenerationInputField('自定义规范提示词', values.customPrompt),
+      references,
+    };
+  }
+
+  const baseFields = [
+    ...createGenerationInputField('玩法设定', values.playSetting),
+    ...createGenerationInputField('美术风格', values.artStyle),
+  ];
+  if (specType === 'character') {
+    baseFields.push(
+      ...createGenerationInputField('头身比', values.bodyRatio),
+      ...createGenerationInputField('角色视角', values.characterView),
+    );
+  }
+  return {
+    fields: baseFields,
+    references,
+  };
+}
+
+export function buildCharacterGenerationInputs(
+  prompt: string,
+  specReference: CharacterReferenceImage | null | undefined,
+  references: CharacterReferenceImage[] | undefined,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField('角色设定', prompt),
+    references: [
+      ...(specReference
+        ? createGenerationInputReference('角色规范', specReference)
+        : []),
+      ...(references ?? []).flatMap((reference, index) =>
+        createGenerationInputReference(`常规参考图 ${index + 1}`, reference),
+      ),
+    ],
+  };
+}
+
+export function buildUiDesignGenerationInputs(
+  prompt: string,
+  specReference: CharacterReferenceImage | null | undefined,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField('用户输入', prompt),
+    references: specReference
+      ? createGenerationInputReference('图标规范', specReference)
+      : [],
+  };
+}
+
+function normalizePublicationGameInfo(
+  gameInfo: PublicationMaterialsGameInfo | null | undefined,
+): PublicationMaterialsGameInfo {
+  return {
+    gameName: gameInfo?.gameName?.trim() ?? '',
+    gameCategories: gameInfo?.gameCategories?.trim() ?? '',
+    gameDescription: gameInfo?.gameDescription?.trim() ?? '',
+  };
+}
+
+export function buildPublicationMaterialsPrompt(
+  gameInfo: PublicationMaterialsGameInfo | null | undefined,
+) {
+  const normalizedGameInfo = normalizePublicationGameInfo(gameInfo);
+  return [
+    ...createGenerationInputField('游戏名', normalizedGameInfo.gameName),
+    ...createGenerationInputField('游戏分类', normalizedGameInfo.gameCategories),
+    ...createGenerationInputField(
+      '一句话描述游戏',
+      normalizedGameInfo.gameDescription,
+    ),
+  ]
+    .map((field) => `${field.title}：${field.value}`)
+    .join('\n');
+}
+
+export function buildPublicationMaterialsGenerationPrompt({
+  gameInfo,
+  workflow,
+}: {
+  gameInfo: PublicationMaterialsGameInfo | null | undefined;
+  workflow: PublicationMaterialsWorkflow;
+}) {
+  const inputPrompt = buildPublicationMaterialsPrompt(gameInfo);
+  return [
+    `【宣发素材类型】${workflow.promptLabel ?? workflow.label}`,
+    inputPrompt ? `【游戏输入】\n${inputPrompt}` : '【游戏输入】\n请根据参考图生成宣发素材。',
+    `【生图约束】\n${workflow.promptConstraints.join('\n')}`,
+    `【参考图约束】\n${workflow.referenceConstraints.join('\n')}`,
+    `【输出检查】\n${workflow.postProcessConstraints.join('\n')}`,
+  ].join('\n\n');
+}
+
+export function buildPublicationMaterialsGenerationInputs(
+  gameInfo: PublicationMaterialsGameInfo | null | undefined,
+  references: CharacterReferenceImage[] | undefined,
+): CanvasGenerationInputs {
+  const normalizedGameInfo = normalizePublicationGameInfo(gameInfo);
+  return {
+    fields: [
+      ...createGenerationInputField('游戏名', normalizedGameInfo.gameName),
+      ...createGenerationInputField('游戏分类', normalizedGameInfo.gameCategories),
+      ...createGenerationInputField(
+        '一句话描述游戏',
+        normalizedGameInfo.gameDescription,
+      ),
+    ],
+    references: (references ?? []).flatMap((reference, index) =>
+      createGenerationInputReference(`宣发参考图 ${index + 1}`, reference),
+    ),
+  };
+}
+
+export function buildIconGenerationInputs(
+  iconDescriptions: string[],
+  specReference: CharacterReferenceImage,
+): CanvasGenerationInputs {
+  return {
+    fields: [
+      {
+        title: '素材描述',
+        value: iconDescriptions.join('\n'),
+      },
+    ],
+    references: createGenerationInputReference('图标规范', specReference),
+  };
+}
+
+export function buildUiDesignAssetExtractionGenerationInputs(
+  sourceLayer: CanvasLayer,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField(
+      '提取提示词',
+      UI_DESIGN_ASSET_EXTRACTION_PROMPT,
+    ),
+    references: createLayerGenerationInputReference('UI设计图', sourceLayer),
+  };
+}
+
+export function buildEditGenerationInputs(
+  title: '修改要求' | '快速编辑提示词' | '重绘提示词',
+  prompt: string,
+  sourceLayer: CanvasLayer,
+): CanvasGenerationInputs {
+  return {
+    fields: createGenerationInputField(title, prompt),
+    references: createLayerGenerationInputReference('参考图', sourceLayer),
+  };
+}
+
+export function buildQuickEditGenerationInputs(
+  title: '快速编辑提示词' | '重绘提示词',
+  prompt: string,
+  _sourceLayer: CanvasLayer,
+  references: CharacterReferenceImage[] | undefined,
+): CanvasGenerationInputs {
+  const limitedReferences = (references ?? []).slice(
+    0,
+    QUICK_EDIT_REFERENCE_LIMIT,
+  );
+  return {
+    fields: createGenerationInputField(title, prompt),
+    references: [
+      // 中文注释：原图作为隐式最后参考图参与生成，但信息面板只展示用户额外选择的参考图。
+      ...limitedReferences.flatMap((reference, index) =>
+        createGenerationInputReference(`参考图 ${index + 1}`, reference),
+      ),
+    ],
+  };
+}
+
+export function isCanvasGenerationDialog(
+  dialog: GenerateDialogState | null,
+): dialog is CanvasGenerationDialogState {
+  return Boolean(
+    dialog?.id &&
+      (dialog.mode === 'generate' ||
+        dialog.mode === 'spec' ||
+        dialog.mode === 'character' ||
+        dialog.mode === 'icon' ||
+        dialog.mode === 'publication' ||
+        dialog.mode === 'ui-design' ||
+        dialog.mode === 'quick-edit' ||
+        dialog.mode === 'character-animation' ||
+        dialog.mode === 'video' ||
+        dialog.mode === 'audio-sound-effect' ||
+        dialog.mode === 'audio-background-music'),
+  );
+}
+
+export function getGenerationFrameAriaLabel(
+  dialog: CanvasGenerationDialogState,
+) {
+  if (dialog.mode === 'character') {
+    return '角色生成占位图';
+  }
+  if (dialog.mode === 'spec') {
+    return '规范生成占位图';
+  }
+  if (dialog.mode === 'icon') {
+    return '图标素材生成占位图';
+  }
+  if (dialog.mode === 'publication') {
+    return '宣发素材生成占位图';
+  }
+  if (dialog.mode === 'ui-design') {
+    return 'UI设计图生成占位图';
+  }
+  if (dialog.mode === 'quick-edit') {
+    return '快速编辑生成占位图';
+  }
+  if (dialog.mode === 'video') {
+    return '视频生成占位图';
+  }
+  if (dialog.mode === 'character-animation') {
+    return '角色动作生成占位图';
+  }
+  if (dialog.mode === 'audio-sound-effect') {
+    return '音效生成占位图';
+  }
+  if (dialog.mode === 'audio-background-music') {
+    return '背景音乐生成占位图';
+  }
+  return '图像生成占位图';
+}
+
+export function getGenerationFrameLabel(dialog: CanvasGenerationDialogState) {
+  if (dialog.mode === 'character') {
+    return 'Character Generator';
+  }
+  if (dialog.mode === 'spec') {
+    return 'Spec Generator';
+  }
+  if (dialog.mode === 'icon') {
+    return 'Icon Generator';
+  }
+  if (dialog.mode === 'publication') {
+    return `${getPublicationMaterialsWorkflow(
+      dialog.publicationWorkflowId ?? 'publication-cover-image',
+    ).englishName} Generator`;
+  }
+  if (dialog.mode === 'ui-design') {
+    return 'UI Design Generator';
+  }
+  if (dialog.mode === 'quick-edit') {
+    return 'Quick Edit Generator';
+  }
+  if (dialog.mode === 'video') {
+    return 'Video Generator';
+  }
+  if (dialog.mode === 'character-animation') {
+    return 'Action Generator';
+  }
+  if (dialog.mode === 'audio-sound-effect') {
+    return 'Sound Generator';
+  }
+  if (dialog.mode === 'audio-background-music') {
+    return 'Music Generator';
+  }
+  return 'Image Generator';
+}
+
+export function resolveImageGenerationErrorMessage(error: unknown) {
+  if (
+    error instanceof ApiClientError &&
+    (error.status === 401 || error.status === 403)
+  ) {
+    return '请先登录后再生成图片';
+  }
+
+  return error instanceof Error && error.message.trim()
+    ? error.message
+    : '生成图片失败';
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
new file mode 100644
index 000000000..eacdc479e
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  chooseGenerationPlacement,
+  centerViewportOnPlacement,
+} from './ImageCanvasGenerationPlacementModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+} from './ImageCanvasEditorTypes';
+
+const canvasSize = { width: 900, height: 640 };
+const viewport: CanvasViewport = { x: 10, y: 20, scale: 2 };
+const frame = {
+  x: 0,
+  y: 0,
+  width: 420,
+  height: 420,
+  originalWidth: 2048,
+  originalHeight: 2048,
+};
+
+function layer(overrides: Partial<CanvasLayer>): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '图片',
+    src: '/image.png',
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    originalWidth: 100,
+    originalHeight: 100,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function generationDialog(
+  overrides: Partial<CanvasGenerationDialogState>,
+): CanvasGenerationDialogState {
+  return {
+    id: 'dialog-1',
+    mode: 'generate',
+    prompt: '',
+    status: 'idle',
+    placeholder: {
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      originalWidth: 2048,
+      originalHeight: 2048,
+    },
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasGenerationPlacementModel', () => {
+  it('places an empty-canvas generation frame at the current viewport center', () => {
+    const placement = chooseGenerationPlacement({
+      canvasSize,
+      viewport,
+      frame,
+      layers: [],
+      generationDialogs: [],
+    });
+
+    expect(placement).toEqual({
+      x: 10,
+      y: -60,
+      width: 420,
+      height: 420,
+      originalWidth: 2048,
+      originalHeight: 2048,
+    });
+  });
+
+  it('keeps the nearest non-overlapping gap from visible layers and generation placeholders', () => {
+    const placement = chooseGenerationPlacement({
+      canvasSize,
+      viewport,
+      frame: { ...frame, width: 100, height: 100 },
+      layers: [
+        layer({ id: 'center', x: 170, y: 110, width: 120, height: 120 }),
+        layer({ id: 'right', x: 322, y: 110, width: 100, height: 120 }),
+        layer({
+          id: 'hidden',
+          hidden: true,
+          x: 18,
+          y: 118,
+          width: 100,
+          height: 100,
+        }),
+      ],
+      generationDialogs: [
+        {
+          id: 'dialog-left',
+          mode: 'generate',
+          prompt: '',
+          status: 'idle',
+          placeholder: {
+            x: 18,
+            y: 118,
+            width: 100,
+            height: 100,
+            originalWidth: 2048,
+            originalHeight: 2048,
+          },
+        },
+      ],
+    });
+
+    expect(placement.x).toBe(170);
+    expect(placement.y).toBe(-22);
+  });
+
+  it('does not treat hidden layers as generation placement blockers', () => {
+    const placement = chooseGenerationPlacement({
+      canvasSize,
+      viewport,
+      frame: { ...frame, width: 100, height: 100 },
+      layers: [
+        layer({
+          id: 'hidden-center',
+          hidden: true,
+          x: 170,
+          y: 110,
+          width: 100,
+          height: 100,
+        }),
+      ],
+      generationDialogs: [],
+    });
+
+    expect(placement.x).toBe(170);
+    expect(placement.y).toBe(100);
+  });
+
+  it('chooses the nearest empty slot when multiple blockers surround the viewport center', () => {
+    const placement = chooseGenerationPlacement({
+      canvasSize: { width: 1000, height: 1000 },
+      viewport: { x: 500, y: 500, scale: 1 },
+      frame: { ...frame, width: 100, height: 100 },
+      layers: [
+        layer({
+          id: 'left-blocker',
+          x: -148,
+          y: -68,
+          width: 96,
+          height: 136,
+        }),
+        layer({
+          id: 'top-blocker',
+          x: -68,
+          y: -148,
+          width: 136,
+          height: 96,
+        }),
+      ],
+      generationDialogs: [],
+    });
+
+    expect(placement.x).toBe(-20);
+    expect(placement.y).toBe(-20);
+  });
+
+  it('avoids existing generation placeholders when choosing a new placement', () => {
+    const placement = chooseGenerationPlacement({
+      canvasSize,
+      viewport,
+      frame: { ...frame, width: 100, height: 100 },
+      layers: [],
+      generationDialogs: [
+        generationDialog({
+          id: 'existing-placeholder',
+          placeholder: {
+            x: 170,
+            y: 110,
+            width: 100,
+            height: 100,
+            originalWidth: 2048,
+            originalHeight: 2048,
+          },
+        }),
+      ],
+    });
+
+    expect(placement.x).toBe(170);
+    expect(placement.y).toBe(-22);
+  });
+
+  it('centers the viewport on the chosen placement without changing zoom', () => {
+    const zoomedViewport = { ...viewport, scale: 1.75 };
+    const nextViewport = centerViewportOnPlacement({
+      canvasSize,
+      viewport: zoomedViewport,
+      placement: {
+        x: 170,
+        y: 262,
+        width: 100,
+        height: 100,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+    });
+
+    expect(nextViewport.scale).toBe(zoomedViewport.scale);
+    expect(nextViewport).toEqual({ x: 65, y: -226, scale: 1.75 });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationPlacementModel.ts b/src/components/image-editor/ImageCanvasGenerationPlacementModel.ts
new file mode 100644
index 000000000..dfe159919
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationPlacementModel.ts
@@ -0,0 +1,277 @@
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+
+type CanvasSize = { width: number; height: number };
+type GenerationFrame = NonNullable<GenerateDialogState['placeholder']>;
+type Rect = { x: number; y: number; width: number; height: number };
+
+const GENERATION_PLACEMENT_GAP = 32;
+const MAX_PLACEMENT_RING = 12;
+
+function getViewportWorldCenter({
+  canvasSize,
+  viewport,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}) {
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  return {
+    x: (canvasSize.width / 2 - viewport.x) / safeScale,
+    y: (canvasSize.height / 2 - viewport.y) / safeScale,
+  };
+}
+
+function expandRect(rect: Rect, gap: number): Rect {
+  return {
+    x: rect.x - gap,
+    y: rect.y - gap,
+    width: rect.width + gap * 2,
+    height: rect.height + gap * 2,
+  };
+}
+
+function rectsOverlap(a: Rect, b: Rect) {
+  return (
+    a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+  );
+}
+
+function distanceSquared(
+  a: { x: number; y: number },
+  b: { x: number; y: number },
+) {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return dx * dx + dy * dy;
+}
+
+function buildBlockingRects({
+  layers,
+  generationDialogs,
+}: {
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+}) {
+  return [
+    ...layers
+      .filter((layer) => !layer.hidden)
+      .map((layer) => ({
+        x: layer.x,
+        y: layer.y,
+        width: layer.width,
+        height: layer.height,
+      })),
+    ...generationDialogs.flatMap((dialog) =>
+      dialog.placeholder
+        ? [
+            {
+              x: dialog.placeholder.x,
+              y: dialog.placeholder.y,
+              width: dialog.placeholder.width,
+              height: dialog.placeholder.height,
+            },
+          ]
+        : [],
+    ),
+  ].map((rect) => expandRect(rect, GENERATION_PLACEMENT_GAP));
+}
+
+function isFree(candidate: Rect, blockingRects: Rect[]) {
+  return !blockingRects.some((rect) => rectsOverlap(candidate, rect));
+}
+
+function createCandidate({
+  center,
+  frame,
+  offsetX,
+  offsetY,
+}: {
+  center: { x: number; y: number };
+  frame: Pick<GenerationFrame, 'width' | 'height'>;
+  offsetX: number;
+  offsetY: number;
+}): Rect {
+  return {
+    x: center.x - frame.width / 2 + offsetX,
+    y: center.y - frame.height / 2 + offsetY,
+    width: frame.width,
+    height: frame.height,
+  };
+}
+
+function pushUniqueCandidate(candidates: Rect[], candidate: Rect) {
+  if (
+    candidates.some(
+      (current) => current.x === candidate.x && current.y === candidate.y,
+    )
+  ) {
+    return;
+  }
+  candidates.push(candidate);
+}
+
+function buildPlacementCandidates({
+  center,
+  frame,
+  blockingRects,
+}: {
+  center: { x: number; y: number };
+  frame: Pick<GenerationFrame, 'width' | 'height'>;
+  blockingRects: Rect[];
+}) {
+  const baseX = center.x - frame.width / 2;
+  const baseY = center.y - frame.height / 2;
+  const stepX = frame.width + GENERATION_PLACEMENT_GAP;
+  const stepY = frame.height + GENERATION_PLACEMENT_GAP;
+  const candidates: Rect[] = [];
+  pushUniqueCandidate(candidates, {
+    x: baseX,
+    y: baseY,
+    width: frame.width,
+    height: frame.height,
+  });
+
+  blockingRects.forEach((rect) => {
+    [
+      { x: rect.x + rect.width, y: baseY },
+      { x: baseX, y: rect.y + rect.height },
+      { x: rect.x - frame.width, y: baseY },
+      { x: baseX, y: rect.y - frame.height },
+      { x: rect.x + rect.width, y: rect.y + rect.height },
+      { x: rect.x - frame.width, y: rect.y + rect.height },
+      { x: rect.x + rect.width, y: rect.y - frame.height },
+      { x: rect.x - frame.width, y: rect.y - frame.height },
+    ].forEach((candidate) =>
+      pushUniqueCandidate(candidates, {
+        ...candidate,
+        width: frame.width,
+        height: frame.height,
+      }),
+    );
+  });
+
+  // 组合不同阻挡物的水平 / 垂直边界，覆盖中心被多块图层夹住时的最近空位。
+  const edgeXs = new Set<number>([baseX]);
+  const edgeYs = new Set<number>([baseY]);
+  blockingRects.forEach((rect) => {
+    edgeXs.add(rect.x + rect.width);
+    edgeXs.add(rect.x - frame.width);
+    edgeYs.add(rect.y + rect.height);
+    edgeYs.add(rect.y - frame.height);
+  });
+  edgeXs.forEach((x) => {
+    edgeYs.forEach((y) => {
+      pushUniqueCandidate(candidates, {
+        x,
+        y,
+        width: frame.width,
+        height: frame.height,
+      });
+    });
+  });
+
+  for (let ring = 1; ring <= MAX_PLACEMENT_RING; ring += 1) {
+    const offsets = [
+      { x: ring, y: 0 },
+      { x: 0, y: ring },
+      { x: -ring, y: 0 },
+      { x: 0, y: -ring },
+      { x: ring, y: ring },
+      { x: -ring, y: ring },
+      { x: ring, y: -ring },
+      { x: -ring, y: -ring },
+    ];
+    offsets.forEach((offset) =>
+      pushUniqueCandidate(
+        candidates,
+        createCandidate({
+          center,
+          frame,
+          offsetX: offset.x * stepX,
+          offsetY: offset.y * stepY,
+        }),
+      ),
+    );
+  }
+
+  return candidates.sort((a, b) => {
+    const aDistance = distanceSquared(
+      { x: a.x + a.width / 2, y: a.y + a.height / 2 },
+      center,
+    );
+    const bDistance = distanceSquared(
+      { x: b.x + b.width / 2, y: b.y + b.height / 2 },
+      center,
+    );
+    if (aDistance !== bDistance) {
+      return aDistance - bDistance;
+    }
+    const aDownBias = a.y >= baseY ? 0 : 1;
+    const bDownBias = b.y >= baseY ? 0 : 1;
+    if (aDownBias !== bDownBias) {
+      return aDownBias - bDownBias;
+    }
+    if (a.x !== b.x) {
+      return a.x - b.x;
+    }
+    return a.y - b.y;
+  });
+}
+
+export function chooseGenerationPlacement({
+  canvasSize,
+  viewport,
+  frame,
+  layers,
+  generationDialogs,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  frame: GenerationFrame;
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+}): GenerationFrame {
+  const center = getViewportWorldCenter({ canvasSize, viewport });
+  const blockingRects = buildBlockingRects({ layers, generationDialogs });
+  const candidates = buildPlacementCandidates({ center, frame, blockingRects });
+  const fallbackPlacement = createCandidate({
+    center,
+    frame,
+    offsetX: 0,
+    offsetY: 0,
+  });
+  const placement =
+    candidates.find((candidate) => isFree(candidate, blockingRects)) ??
+    fallbackPlacement;
+
+  return {
+    ...frame,
+    x: placement.x,
+    y: placement.y,
+  };
+}
+
+export function centerViewportOnPlacement({
+  canvasSize,
+  viewport,
+  placement,
+}: {
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  placement: GenerationFrame;
+}): CanvasViewport {
+  const scale = viewport.scale > 0 ? viewport.scale : 1;
+  return {
+    x: canvasSize.width / 2 - (placement.x + placement.width / 2) * scale,
+    y: canvasSize.height / 2 - (placement.y + placement.height / 2) * scale,
+    scale,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
new file mode 100644
index 000000000..bbba26d12
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts
@@ -0,0 +1,923 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import {
+  buildCharacterAnimationSubmissionPlan,
+  buildIconSpritesheetGenerationSubmissionPlan,
+  buildImageGenerationSubmissionPlan,
+} from './ImageCanvasGenerationSubmissionModel';
+import {
+  BACKGROUND_MUSIC_MODEL_SUNO,
+  calculateCharacterAnimationPrice,
+  calculateEditorBackgroundMusicPrice,
+  calculateEditorIconSpritesheetPrice,
+  calculateEditorSoundEffectPrice,
+  calculateEditorVideoPrice,
+  CHARACTER_ANIMATION_MODEL,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  IMAGE_MODEL_NANOBANANA2,
+} from './ImageCanvasGenerationModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '源图',
+    src: 'data:image/png;base64,source',
+    x: 120,
+    y: 140,
+    width: 320,
+    height: 240,
+    originalWidth: 1024,
+    originalHeight: 768,
+    zIndex: 2,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasGenerationSubmissionModel', () => {
+  it('builds normal image generation submission plans', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'generate',
+        prompt: '  一张发光主视觉  ',
+        status: 'idle',
+      },
+      layers: [],
+      nextGeneratedIndex: 3,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      normalizedPrompt: '一张发光主视觉',
+      input: {
+        prompt: '一张发光主视觉',
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+      },
+      result: {
+        title: '生成图片 3',
+        generationInputs: {
+          fields: [{ title: '生成提示词', value: '一张发光主视觉' }],
+          references: [],
+        },
+      },
+      rememberImageModel: 'gemini-3.1-flash-image-preview',
+    });
+  });
+
+  it('normalizes legacy nanobanana aliases before submitting image generation', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'generate',
+        prompt: '一张明亮图片',
+        status: 'idle',
+        imageModel: 'nanobanana2',
+        aspectRatio: '16:9',
+        imageSize: '2K',
+      },
+      layers: [],
+      nextGeneratedIndex: 5,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      input: {
+        model: IMAGE_MODEL_NANOBANANA2,
+        aspectRatio: '16:9',
+        imageSize: '2K',
+      },
+      rememberImageModel: IMAGE_MODEL_NANOBANANA2,
+    });
+  });
+
+  it('builds edit submission plans with the source layer snapshot', () => {
+    const sourceLayer = createLayer();
+
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'edit',
+        prompt: '',
+        status: 'idle',
+        sourceLayerId: sourceLayer.id,
+      },
+      layers: [sourceLayer],
+      nextGeneratedIndex: 4,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'edit',
+      normalizedPrompt: '修改当前图片',
+      sourceLayer,
+      generationInputs: {
+        fields: [{ title: '修改要求', value: '修改当前图片' }],
+        references: [
+          {
+            title: '参考图',
+            label: '源图',
+            refType: 'project-resource',
+            refId: 'resource-source',
+          },
+        ],
+      },
+    });
+  });
+
+  it('builds spec generation plans with reference prompt semantics', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'spec',
+        prompt: '',
+        status: 'idle',
+        specType: 'icon',
+        specValues: {
+          playSetting: '休闲消除',
+          artStyle: '清爽卡通',
+          bodyRatio: '3',
+          characterView: '',
+          customPrompt: '',
+        },
+        specReference: {
+          id: 'spec-ref',
+          label: '参考.png',
+          src: 'data:image/png;base64,ref',
+          resourceId: 'resource-spec-ref',
+        },
+      },
+      layers: [],
+      nextGeneratedIndex: 8,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      normalizedPrompt: 'AI 生成图片',
+      input: {
+        size: '2048x1152',
+        model: 'gpt-image-2',
+        aspectRatio: '16:9',
+        imageSize: '2K',
+        kind: 'spec',
+        referenceImageSrcs: ['data:image/png;base64,ref'],
+        prompt: expect.stringContaining('参考图生成规范'),
+      },
+      result: {
+        assetKind: 'icon-spec',
+        title: '图标规范 8',
+      },
+    });
+    expect(plan.kind === 'image' ? plan.result.generationInputs : null).toEqual({
+      fields: [
+        { title: '玩法设定', value: '休闲消除' },
+        { title: '美术风格', value: '清爽卡通' },
+      ],
+      references: [
+        {
+          title: '参考图',
+          label: '参考.png',
+          refType: 'project-resource',
+          refId: 'resource-spec-ref',
+        },
+      ],
+    });
+  });
+
+  it('treats the renamed UI spec entry as an icon spec asset', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'spec',
+        prompt: '',
+        status: 'idle',
+        specType: 'ui',
+        specValues: {
+          playSetting: '消除类派对玩法',
+          artStyle: '糖果玻璃拟物',
+          bodyRatio: '3',
+          characterView: '',
+          customPrompt: '',
+        },
+      },
+      layers: [],
+      nextGeneratedIndex: 2,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      result: {
+        assetKind: 'icon-spec',
+        title: '图标规范 2',
+      },
+    });
+  });
+
+  it('builds character plans with references and remembered model', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'character',
+        prompt: '  白发骑士  ',
+        status: 'idle',
+        imageModel: 'gpt-image-2',
+        aspectRatio: '2:3',
+        imageSize: '2K',
+        characterSpecReference: {
+          id: 'spec',
+          label: '角色规范',
+          src: 'data:image/png;base64,spec',
+          resourceId: 'resource-character-spec',
+        },
+        characterReferences: [
+          {
+            id: 'ref-1',
+            label: '盔甲参考',
+            src: 'data:image/png;base64,armor',
+            resourceId: 'resource-armor',
+          },
+        ],
+      },
+      layers: [],
+      nextGeneratedIndex: 9,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      normalizedPrompt: '白发骑士',
+      input: {
+        prompt: '白发骑士',
+        kind: 'character',
+        model: 'gpt-image-2',
+        aspectRatio: '2:3',
+        imageSize: '2K',
+        referenceImageSrcs: [
+          'data:image/png;base64,spec',
+          'data:image/png;base64,armor',
+        ],
+      },
+      result: {
+        assetKind: 'character',
+        title: '角色形象 9',
+      },
+      rememberImageModel: 'gpt-image-2',
+    });
+    expect(plan.kind === 'image' ? plan.result.generationInputs : null).toEqual({
+      fields: [{ title: '角色设定', value: '白发骑士' }],
+      references: [
+        {
+          title: '角色规范',
+          label: '角色规范',
+          refType: 'project-resource',
+          refId: 'resource-character-spec',
+        },
+        {
+          title: '常规参考图 1',
+          label: '盔甲参考',
+          refType: 'project-resource',
+          refId: 'resource-armor',
+        },
+      ],
+    });
+  });
+
+  it('builds publication material plans with structured game fields', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'publication',
+        prompt: '',
+        status: 'idle',
+        publicationGameInfo: {
+          gameName: ' 重庆洪崖洞火锅 ',
+          gameCategories: '抓大鹅、休闲、治愈、手绘风',
+          gameDescription: '在一堆物品里点击，找到三个一样的物品将其消除',
+        },
+        publicationReferences: [
+          {
+            id: 'ref-1',
+            label: '参考图',
+            src: 'data:image/png;base64,ref',
+            resourceId: 'resource-publication-ref',
+          },
+        ],
+      },
+      layers: [],
+      nextGeneratedIndex: 10,
+    });
+
+    expect(plan).toEqual({
+      kind: 'image',
+      normalizedPrompt: [
+        '游戏名：重庆洪崖洞火锅',
+        '游戏分类：抓大鹅、休闲、治愈、手绘风',
+        '一句话描述游戏：在一堆物品里点击，找到三个一样的物品将其消除',
+      ].join('\n'),
+      input: {
+        prompt: expect.stringContaining('【宣发素材类型】游戏首图'),
+        size: '720x540',
+        kind: 'publication-material',
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '4:3',
+        imageSize: '1K',
+        referenceImageSrcs: ['data:image/png;base64,ref'],
+      },
+      result: {
+        title: '10 宣发素材',
+        generationInputs: {
+          fields: [
+            { title: '游戏名', value: '重庆洪崖洞火锅' },
+            { title: '游戏分类', value: '抓大鹅、休闲、治愈、手绘风' },
+            {
+              title: '一句话描述游戏',
+              value: '在一堆物品里点击，找到三个一样的物品将其消除',
+            },
+          ],
+          references: [
+            {
+              title: '宣发参考图 1',
+              label: '参考图',
+              refType: 'project-resource',
+              refId: 'resource-publication-ref',
+            },
+          ],
+        },
+      },
+      rememberImageModel: 'gemini-3.1-flash-image-preview',
+    });
+    const prompt = plan.kind === 'image' ? plan.input.prompt : '';
+    expect(prompt).toContain('游戏名：重庆洪崖洞火锅');
+    expect(prompt).toContain('标题文字必须直接进入画面');
+    expect(prompt).toContain('输出检查：720 x 540，4:3');
+  });
+
+  it('builds detail gallery publication plans as one 720p portrait image', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'publication',
+        prompt: '',
+        status: 'idle',
+        publicationWorkflowId: 'publication-detail-gallery',
+        publicationGameInfo: {
+          gameName: '云朵消消乐',
+          gameCategories: '',
+          gameDescription: '',
+        },
+      },
+      layers: [],
+      nextGeneratedIndex: 11,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      input: {
+        prompt: expect.stringContaining('【宣发素材类型】详情页单图'),
+        size: '720x1280',
+        kind: 'publication-material',
+        aspectRatio: '9:16',
+        imageSize: '1K',
+      },
+      result: {
+        title: '11 宣发素材',
+      },
+    });
+    expect(plan.kind === 'image' ? plan.input.prompt : '').toContain(
+      '本次只生成一张 720 x 1280 竖版详情图',
+    );
+    expect(plan.kind === 'image' ? plan.input.prompt : '').toContain(
+      '不是五图合集或拼贴',
+    );
+  });
+
+  it('builds promo poster publication plans as 720p landscape images', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'publication',
+        prompt: '',
+        status: 'idle',
+        publicationWorkflowId: 'publication-promo-poster',
+        publicationGameInfo: {
+          gameName: '火锅节活动',
+          gameCategories: '',
+          gameDescription: '',
+        },
+      },
+      layers: [],
+      nextGeneratedIndex: 12,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'image',
+      input: {
+        prompt: expect.stringContaining('【宣发素材类型】运营海报'),
+        size: '1280x720',
+        kind: 'publication-material',
+        aspectRatio: '16:9',
+        imageSize: '1K',
+      },
+      result: {
+        title: '12 宣发素材',
+      },
+    });
+    expect(plan.kind === 'image' ? plan.input.prompt : '').toContain(
+      '16:9 横版 720p，建议 1280 x 720',
+    );
+    expect(plan.kind === 'image' ? plan.input.prompt : '').toContain(
+      '此处换上你的游戏二维码',
+    );
+    expect(plan.kind === 'image' ? plan.input.prompt : '').toContain(
+      '方块内部上方用黑色小字',
+    );
+  });
+
+  it('builds publication material plans with selected image model', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'publication',
+        prompt: '',
+        status: 'idle',
+        publicationWorkflowId: 'publication-promo-poster',
+        publicationGameInfo: {
+          gameName: '星际塔防',
+          gameCategories: '',
+          gameDescription: '',
+        },
+        publicationReferences: [],
+        imageModel: 'gpt-image-2',
+      },
+      layers: [],
+      nextGeneratedIndex: 4,
+    });
+
+    expect(plan.kind).toBe('image');
+    if (plan.kind !== 'image') {
+      return;
+    }
+    expect(plan.input).toEqual(
+      expect.objectContaining({
+        kind: 'publication-material',
+        model: 'gpt-image-2',
+        size: '1280x720',
+        aspectRatio: '16:9',
+        imageSize: '1K',
+      }),
+    );
+    expect(plan.rememberImageModel).toBe('gpt-image-2');
+  });
+
+  it('throws when edit source layer is missing', () => {
+    expect(() =>
+      buildImageGenerationSubmissionPlan({
+        dialog: {
+          mode: 'edit',
+          prompt: '修图',
+          status: 'idle',
+          sourceLayerId: 'missing-layer',
+        },
+        layers: [],
+        nextGeneratedIndex: 1,
+      }),
+    ).toThrow('未找到要修改的图片');
+  });
+
+  it('returns an icon spritesheet error when the spec reference is missing', () => {
+    const plan = buildIconSpritesheetGenerationSubmissionPlan({
+      mode: 'icon',
+      prompt: '',
+      status: 'idle',
+      iconDescriptions: ['返回按钮'],
+    });
+
+    expect(plan).toEqual({
+      ok: false,
+      errorMessage: '请选择图标规范',
+    });
+  });
+
+  it('returns an icon spritesheet error when descriptions are empty', () => {
+    const plan = buildIconSpritesheetGenerationSubmissionPlan({
+      mode: 'icon',
+      prompt: '',
+      status: 'idle',
+      iconSpecReference: {
+        id: 'icon-spec',
+        label: '图标规范',
+        src: 'data:image/png;base64,spec',
+        resourceId: 'resource-icon-spec',
+      },
+      iconDescriptions: [' ', '\n'],
+    });
+
+    expect(plan).toEqual({
+      ok: false,
+      errorMessage: '请填写素材描述',
+    });
+  });
+
+  it('builds icon spritesheet plans with trimmed descriptions and references', () => {
+    const plan = buildIconSpritesheetGenerationSubmissionPlan({
+      mode: 'icon',
+      prompt: '  返回按钮  \n\n设置按钮',
+      status: 'idle',
+      imageModel: 'gpt-image-2',
+      aspectRatio: '3:2',
+      imageSize: '2K',
+      iconSpecReference: {
+        id: 'icon-spec',
+        label: '图标规范',
+        src: 'data:image/png;base64,spec',
+        resourceId: 'resource-icon-spec',
+      },
+      iconDescriptions: ['旧返回', '旧设置'],
+    });
+
+    expect(plan).toEqual({
+      ok: true,
+      iconDescriptions: ['返回按钮', '设置按钮'],
+      input: {
+        referenceImageSrc: 'data:image/png;base64,spec',
+        iconDescriptions: ['返回按钮', '设置按钮'],
+        model: 'gpt-image-2',
+        aspectRatio: '3:2',
+        imageSize: '2K',
+        priceMudPoints: calculateEditorIconSpritesheetPrice('gpt-image-2'),
+      },
+      generationInputs: {
+        fields: [{ title: '素材描述', value: '返回按钮\n设置按钮' }],
+        references: [
+          {
+            title: '图标规范',
+            label: '图标规范',
+            refType: 'project-resource',
+            refId: 'resource-icon-spec',
+          },
+        ],
+      },
+      rememberImageModel: 'gpt-image-2',
+    });
+  });
+
+  it('builds character animation plans with trimmed prompt and object key source', () => {
+    const sourceLayer = createLayer({
+      id: 'character-layer',
+      title: '角色图',
+      objectKey: 'generated/character.png',
+      assetKind: 'character',
+      originalWidth: 960,
+      originalHeight: 1280,
+    });
+
+    const plan = buildCharacterAnimationSubmissionPlan({
+      panel: {
+        sourceLayerId: 'character-layer',
+        promptText: '  循环奔跑动作  ',
+        resolution: '720p',
+        ratio: 'same',
+        frameCount: 48,
+        durationSeconds: 6,
+        status: 'idle',
+      },
+      sourceLayer,
+    });
+
+    expect(plan).toEqual({
+      promptText: '循环奔跑动作',
+      input: {
+        sourceLayerId: 'character-layer',
+        sourceImageSrc: 'generated/character.png',
+        sourceWidth: 960,
+        sourceHeight: 1280,
+        promptText: '循环奔跑动作',
+        resolution: '720p',
+        ratio: 'same',
+        frameCount: 48,
+        durationSeconds: 6,
+        priceMudPoints: calculateCharacterAnimationPrice(
+          CHARACTER_ANIMATION_MODEL,
+          '720p',
+          6,
+        ),
+        model: 'seedance2.0-fast',
+      },
+    });
+  });
+
+
+  it('builds seedance video plans with multimodal references', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'video',
+        prompt: '  根据参考生成角色宣传片  ',
+        status: 'idle',
+        videoModel: 'seedance2.0-fast',
+        videoResolution: '720p',
+        videoDurationSeconds: 5,
+        generationReferences: [
+          {
+            id: 'image-ref',
+            label: '参考图.png',
+            src: 'data:image/png;base64,image',
+            mediaType: 'image',
+            mimeType: 'image/png',
+            sizeBytes: 1024,
+            resourceId: 'resource-video-image-ref',
+          },
+          {
+            id: 'video-ref',
+            label: '参考视频.mp4',
+            src: 'https://signed.example.com/video.mp4',
+            mediaType: 'video',
+            mimeType: 'video/mp4',
+            sizeBytes: 2048,
+            durationSeconds: 4,
+            objectKey:
+              'generated-character-drafts/editor/seedance-references/video/video.mp4',
+            resourceId: 'resource-video-ref',
+          },
+          {
+            id: 'audio-ref',
+            label: '参考音频.mp3',
+            src: 'https://signed.example.com/audio.mp3',
+            mediaType: 'audio',
+            mimeType: 'audio/mpeg',
+            sizeBytes: 512,
+            durationSeconds: 3,
+            objectKey:
+              'generated-character-drafts/editor/seedance-references/audio/audio.mp3',
+            resourceId: 'resource-audio-ref',
+          },
+        ],
+      },
+      layers: [],
+      nextGeneratedIndex: 6,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'video',
+      input: {
+        model: 'seedance2.0-fast',
+        referenceImageSrcs: ['data:image/png;base64,image'],
+        referenceVideoSrcs: [
+          'generated-character-drafts/editor/seedance-references/video/video.mp4',
+        ],
+        referenceAudioSrcs: [
+          'generated-character-drafts/editor/seedance-references/audio/audio.mp3',
+        ],
+      },
+      result: {
+        generationInputs: {
+          references: [
+            {
+              title: '参考图 1',
+              label: '参考图.png',
+              refType: 'project-resource',
+              refId: 'resource-video-image-ref',
+            },
+            {
+              title: '参考视频 1',
+              label: '参考视频.mp4',
+              refType: 'project-resource',
+              refId: 'resource-video-ref',
+            },
+            {
+              title: '参考音频 1',
+              label: '参考音频.mp3',
+              refType: 'project-resource',
+              refId: 'resource-audio-ref',
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it('does not submit references to non seedance video models', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'video',
+        prompt: '镜头推进',
+        status: 'idle',
+        videoModel: 'kling3.0',
+        generationReferences: [
+          {
+            id: 'image-ref',
+            label: '参考图.png',
+            src: 'data:image/png;base64,image',
+            mediaType: 'image',
+          },
+        ],
+      },
+      layers: [],
+      nextGeneratedIndex: 2,
+    });
+
+    expect(plan.kind).toBe('video');
+    if (plan.kind === 'video') {
+      expect(plan.input).not.toHaveProperty('referenceImageSrcs');
+      expect(plan.input).not.toHaveProperty('referenceVideoSrcs');
+      expect(plan.input).not.toHaveProperty('referenceAudioSrcs');
+    }
+  });
+
+  it('rejects seedance video plans that only contain audio references', () => {
+    expect(() =>
+      buildImageGenerationSubmissionPlan({
+        dialog: {
+          mode: 'video',
+          prompt: '根据音频生成视频',
+          status: 'idle',
+          videoModel: 'seedance2.0',
+          generationReferences: [
+            {
+              id: 'audio-ref',
+              label: '旁白.wav',
+              src: 'data:audio/wav;base64,audio',
+              mediaType: 'audio',
+              durationSeconds: 4,
+            },
+          ],
+        },
+        layers: [],
+        nextGeneratedIndex: 2,
+      }),
+    ).toThrow('参考音频必须搭配参考图片或参考视频');
+  });
+
+  it('rejects seedance video plans that exceed reference count limits', () => {
+    expect(() =>
+      buildImageGenerationSubmissionPlan({
+        dialog: {
+          mode: 'video',
+          prompt: '生成视频',
+          status: 'idle',
+          videoModel: 'seedance2.0-fast',
+          generationReferences: Array.from({ length: 10 }, (_, index) => ({
+            id: `image-${index}`,
+            label: `参考图${index}.png`,
+            src: `data:image/png;base64,${index}`,
+            mediaType: 'image' as const,
+          })),
+        },
+        layers: [],
+        nextGeneratedIndex: 2,
+      }),
+    ).toThrow('参考图片最多 9 张');
+  });
+
+  it('builds video generation plans with seedance fast as the fallback model', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'video',
+        prompt: '  角色绕场一周  ',
+        status: 'idle',
+        generationReferences: [],
+        videoResolution: '480p',
+        videoDurationSeconds: 4,
+      },
+      layers: [],
+      nextGeneratedIndex: 3,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'video',
+      normalizedPrompt: '角色绕场一周',
+      input: {
+        model: 'seedance2.0-fast',
+        priceMudPoints: calculateEditorVideoPrice('seedance2.0-fast', '480p', 4),
+      },
+      result: {
+        title: '生成视频 3',
+      },
+    });
+  });
+
+  it('builds video generation plans with explicit seedance standard model', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'video',
+        prompt: '  生成电影感开场动画  ',
+        status: 'idle',
+        videoModel: 'seedance2.0',
+        videoResolution: '720p',
+        videoDurationSeconds: 5,
+      },
+      layers: [],
+      nextGeneratedIndex: 7,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'video',
+      normalizedPrompt: '生成电影感开场动画',
+      input: {
+        prompt: '生成电影感开场动画',
+        model: 'seedance2.0',
+        resolution: '720p',
+        durationSeconds: 5,
+        priceMudPoints: calculateEditorVideoPrice('seedance2.0', '720p', 5),
+      },
+      result: {
+        title: '生成视频 7',
+      },
+    });
+  });
+
+  it('builds game sound effect audio submission plans', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'audio-sound-effect',
+        prompt: '  金币掉落叮当声  ',
+        status: 'idle',
+        soundDurationSeconds: 7,
+      },
+      layers: [],
+      nextGeneratedIndex: 4,
+    });
+
+    expect(plan).toEqual({
+      kind: 'audio',
+      audioKind: 'sound-effect',
+      normalizedPrompt: '金币掉落叮当声',
+      input: {
+        prompt: '金币掉落叮当声',
+        model: 'audio1.0',
+        duration: 7,
+        priceMudPoints: calculateEditorSoundEffectPrice(DEFAULT_SOUND_EFFECT_MODEL),
+      },
+      result: {
+        title: '游戏音效 4',
+        generationInputs: {
+          fields: [
+            { title: 'prompt', value: '金币掉落叮当声' },
+            { title: 'model', value: 'audio1.0' },
+            { title: 'duration', value: '7秒' },
+          ],
+          references: [],
+        },
+      },
+    });
+  });
+
+  it('uses 5 seconds as default game sound effect duration', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'audio-sound-effect',
+        prompt: '按钮确认短促音',
+        status: 'idle',
+      },
+      layers: [],
+      nextGeneratedIndex: 6,
+    });
+
+    expect(plan).toMatchObject({
+      kind: 'audio',
+      audioKind: 'sound-effect',
+      input: {
+        prompt: '按钮确认短促音',
+        model: 'audio1.0',
+        duration: 5,
+      },
+      result: {
+        generationInputs: {
+          fields: [
+            { title: 'prompt', value: '按钮确认短促音' },
+            { title: 'model', value: 'audio1.0' },
+            { title: 'duration', value: '5秒' },
+          ],
+        },
+      },
+    });
+  });
+
+  it('builds game background music audio submission plans with instrumental fixed to true', () => {
+    const plan = buildImageGenerationSubmissionPlan({
+      dialog: {
+        mode: 'audio-background-music',
+        prompt: '  温暖轻快的森林冒险背景音乐  ',
+        status: 'idle',
+      },
+      layers: [],
+      nextGeneratedIndex: 5,
+    });
+
+    expect(plan).toEqual({
+      kind: 'audio',
+      audioKind: 'background-music',
+      normalizedPrompt: '温暖轻快的森林冒险背景音乐',
+      input: {
+        gptDescriptionPrompt: '温暖轻快的森林冒险背景音乐',
+        makeInstrumental: true,
+        priceMudPoints: calculateEditorBackgroundMusicPrice(
+          BACKGROUND_MUSIC_MODEL_SUNO,
+        ),
+      },
+      result: {
+        title: '游戏背景音乐 5',
+        generationInputs: {
+          fields: [
+            {
+              title: 'gpt_description_prompt',
+              value: '温暖轻快的森林冒险背景音乐',
+            },
+          ],
+          references: [],
+        },
+      },
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
new file mode 100644
index 000000000..f708b9373
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts
@@ -0,0 +1,557 @@
+import type {
+  EditorBackgroundMusicGenerationInput,
+  EditorCharacterAnimationGenerationInput,
+  EditorIconSpritesheetGenerationInput,
+  EditorImageGenerationInput,
+  EditorSoundEffectGenerationInput,
+  EditorVideoGenerationInput,
+} from '../../services/image-editor/editorProjectClient';
+import type {
+  CanvasGenerationInputs,
+  CanvasLayer,
+  CharacterAnimationPanelState,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import {
+  buildBackgroundMusicGenerationInputs,
+  buildCharacterGenerationInputs,
+  buildEditGenerationInputs,
+  buildIconGenerationInputs,
+  buildImageGenerationInputs,
+  buildPublicationMaterialsGenerationInputs,
+  buildPublicationMaterialsGenerationPrompt,
+  buildPublicationMaterialsPrompt,
+  buildSoundEffectGenerationInputs,
+  buildSpecGenerationInputs,
+  buildSpecPrompt,
+  buildUiDesignGenerationInputs,
+  buildVideoGenerationInputs,
+  calculateCharacterAnimationPrice,
+  calculateEditorBackgroundMusicPrice,
+  calculateEditorIconSpritesheetPrice,
+  calculateEditorSoundEffectPrice,
+  calculateEditorVideoPrice,
+  CHARACTER_ANIMATION_MODEL,
+  DEFAULT_BACKGROUND_MUSIC_MODEL,
+  DEFAULT_ICON_DESCRIPTIONS,
+  DEFAULT_SOUND_EFFECT_DURATION_SECONDS,
+  DEFAULT_SOUND_EFFECT_MODEL,
+  DEFAULT_SPEC_FORM_VALUES,
+  DEFAULT_VIDEO_ASPECT_RATIO,
+  DEFAULT_VIDEO_DURATION_SECONDS,
+  DEFAULT_VIDEO_MODEL,
+  DEFAULT_VIDEO_SOUND,
+  DEFAULT_VIDEO_WEB_SEARCH_ENABLED,
+  ICON_DESCRIPTION_LIMIT,
+  normalizeEditorImageModel,
+  resolveCharacterAnimationSourceImageSrc,
+  SEEDANCE_VIDEO_REFERENCE_LIMITS,
+  SPEC_GENERATION_ASPECT_RATIO,
+  SPEC_GENERATION_IMAGE_SIZE,
+  SPEC_GENERATION_MODEL,
+  SPEC_GENERATION_SIZE,
+  SPEC_TYPE_LABEL,
+} from './ImageCanvasGenerationModel';
+import { getPublicationMaterialsWorkflow } from './ImageCanvasPublicationMaterialsModel';
+
+type ImageGenerationSubmissionOptions = {
+  dialog: GenerateDialogState;
+  layers: CanvasLayer[];
+  nextGeneratedIndex: number;
+};
+
+function isSeedanceVideoModel(model: string) {
+  return model === 'seedance2.0' || model === 'seedance2.0-fast';
+}
+
+export function isSeedanceEditorVideoModel(model: string) {
+  return isSeedanceVideoModel(model);
+}
+
+function estimateReferenceRequestBytes(references: Array<{ src: string }>) {
+  // 中文注释：JSON 包装字段还有少量额外字节；这里按 src 字符串长度估算，前后端都会再兜底校验 64MB。
+  return references.reduce((sum, reference) => sum + reference.src.length, 0);
+}
+
+function buildSeedanceVideoReferenceInput(
+  references: NonNullable<GenerateDialogState['generationReferences']>,
+) {
+  const resolveReferenceSource = (reference: { src: string; objectKey?: string | null }) =>
+    reference.objectKey?.trim() || reference.src;
+  const imageReferences = references.filter(
+    (reference) => (reference.mediaType ?? 'image') === 'image',
+  );
+  const videoReferences = references.filter(
+    (reference) => reference.mediaType === 'video',
+  );
+  const audioReferences = references.filter(
+    (reference) => reference.mediaType === 'audio',
+  );
+
+  if (imageReferences.length > SEEDANCE_VIDEO_REFERENCE_LIMITS.image) {
+    throw new Error('参考图片最多 9 张');
+  }
+  if (videoReferences.length > SEEDANCE_VIDEO_REFERENCE_LIMITS.video) {
+    throw new Error('参考视频最多 3 个');
+  }
+  if (audioReferences.length > SEEDANCE_VIDEO_REFERENCE_LIMITS.audio) {
+    throw new Error('参考音频最多 3 个');
+  }
+  if (audioReferences.length && !imageReferences.length && !videoReferences.length) {
+    throw new Error('参考音频必须搭配参考图片或参考视频');
+  }
+  if (
+    estimateReferenceRequestBytes(references) >
+    SEEDANCE_VIDEO_REFERENCE_LIMITS.requestBytes
+  ) {
+    throw new Error('参考文件总请求体不能超过 64MB');
+  }
+
+  return {
+    referenceImageSrcs: imageReferences.map(resolveReferenceSource),
+    referenceVideoSrcs: videoReferences.map(resolveReferenceSource),
+    referenceAudioSrcs: audioReferences.map(resolveReferenceSource),
+  };
+}
+
+function getDialogDefaultPrompt(mode: GenerateDialogState['mode']) {
+  if (mode === 'edit') {
+    return '修改当前图片';
+  }
+  if (mode === 'audio-sound-effect') {
+    return '游戏音效';
+  }
+  if (mode === 'audio-background-music') {
+    return '游戏背景音乐';
+  }
+  return 'AI 生成图片';
+}
+
+export type ImageGenerationSubmissionPlan =
+  | {
+      kind: 'edit';
+      normalizedPrompt: string;
+      sourceLayer: CanvasLayer;
+      generationInputs: CanvasGenerationInputs;
+    }
+  | {
+      kind: 'image';
+      normalizedPrompt: string;
+      input: EditorImageGenerationInput;
+      result: {
+        assetKind?: CanvasLayer['assetKind'];
+        title?: string;
+        generationInputs: CanvasGenerationInputs;
+      };
+      rememberImageModel?: string;
+    }
+  | {
+      kind: 'video';
+      normalizedPrompt: string;
+      input: EditorVideoGenerationInput;
+      result: {
+        title: string;
+        generationInputs: CanvasGenerationInputs;
+      };
+    }
+  | {
+      kind: 'audio';
+      audioKind: 'sound-effect';
+      normalizedPrompt: string;
+      input: EditorSoundEffectGenerationInput;
+      result: {
+        title: string;
+        generationInputs: CanvasGenerationInputs;
+      };
+    }
+  | {
+      kind: 'audio';
+      audioKind: 'background-music';
+      normalizedPrompt: string;
+      input: EditorBackgroundMusicGenerationInput;
+      result: {
+        title: string;
+        generationInputs: CanvasGenerationInputs;
+      };
+    };
+
+export type IconSpritesheetGenerationSubmissionPlan =
+  | {
+      ok: false;
+      errorMessage: string;
+    }
+  | {
+      ok: true;
+      iconDescriptions: string[];
+      input: EditorIconSpritesheetGenerationInput;
+      generationInputs: CanvasGenerationInputs;
+      rememberImageModel: string;
+    };
+
+export type CharacterAnimationSubmissionPlan = {
+  promptText: string;
+  input: EditorCharacterAnimationGenerationInput;
+};
+
+export function buildImageGenerationSubmissionPlan({
+  dialog,
+  layers,
+  nextGeneratedIndex,
+}: ImageGenerationSubmissionOptions): ImageGenerationSubmissionPlan {
+  const normalizedPrompt =
+    dialog.prompt.trim() || getDialogDefaultPrompt(dialog.mode);
+
+  if (dialog.mode === 'edit') {
+    const sourceLayer = layers.find((layer) => layer.id === dialog.sourceLayerId);
+    if (!sourceLayer) {
+      throw new Error('未找到要修改的图片');
+    }
+    return {
+      kind: 'edit',
+      normalizedPrompt,
+      sourceLayer,
+      generationInputs: buildEditGenerationInputs(
+        '修改要求',
+        normalizedPrompt,
+        sourceLayer,
+      ),
+    };
+  }
+
+  if (dialog.mode === 'spec') {
+    const specType = dialog.specType ?? 'custom';
+    const specValues = dialog.specValues ?? DEFAULT_SPEC_FORM_VALUES[specType];
+    return {
+      kind: 'image',
+      normalizedPrompt,
+      input: {
+        prompt: buildSpecPrompt(
+          specType,
+          specValues,
+          Boolean(dialog.specReference?.src),
+        ),
+        size: SPEC_GENERATION_SIZE,
+        model: SPEC_GENERATION_MODEL,
+        aspectRatio: SPEC_GENERATION_ASPECT_RATIO,
+        imageSize: SPEC_GENERATION_IMAGE_SIZE,
+        kind: 'spec',
+        ...(dialog.specReference?.src
+          ? { referenceImageSrcs: [dialog.specReference.src] }
+          : {}),
+      },
+      result: {
+        // 中文注释：生成规范菜单里的“图标规范”沿用历史 ui specType，但产物语义应作为图标规范供图标素材引用。
+        assetKind:
+          specType === 'ui' || specType === 'icon' ? 'icon-spec' : 'spec',
+        title: `${SPEC_TYPE_LABEL[specType]} ${nextGeneratedIndex}`,
+        generationInputs: buildSpecGenerationInputs(
+          specType,
+          specValues,
+          dialog.specReference,
+        ),
+      },
+    };
+  }
+
+  if (dialog.mode === 'character') {
+    const referenceImageSrcs = [
+      dialog.characterSpecReference?.src,
+      ...(dialog.characterReferences ?? []).map((reference) => reference.src),
+    ].filter((src): src is string => Boolean(src));
+    const imageModel = normalizeEditorImageModel(dialog.imageModel);
+    return {
+      kind: 'image',
+      normalizedPrompt,
+      input: {
+        prompt: normalizedPrompt,
+        kind: 'character',
+        model: imageModel,
+        aspectRatio: dialog.aspectRatio ?? '1:1',
+        imageSize: dialog.imageSize ?? '1K',
+        ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}),
+      },
+      result: {
+        assetKind: 'character',
+        title: `角色形象 ${nextGeneratedIndex}`,
+        generationInputs: buildCharacterGenerationInputs(
+          normalizedPrompt,
+          dialog.characterSpecReference,
+          dialog.characterReferences,
+        ),
+      },
+      rememberImageModel: imageModel,
+    };
+  }
+
+  if (dialog.mode === 'ui-design') {
+    const imageModel = normalizeEditorImageModel(dialog.imageModel);
+    const referenceImageSrcs = [dialog.uiDesignSpecReference?.src].filter(
+      (src): src is string => Boolean(src),
+    );
+    return {
+      kind: 'image',
+      normalizedPrompt,
+      input: {
+        prompt: normalizedPrompt,
+        kind: 'ui-design',
+        model: imageModel,
+        aspectRatio: dialog.aspectRatio ?? '16:9',
+        imageSize: dialog.imageSize ?? '1K',
+        ...(referenceImageSrcs.length ? { referenceImageSrcs } : {}),
+      },
+      result: {
+        assetKind: 'ui-design',
+        title: `UI设计图 ${nextGeneratedIndex}`,
+        generationInputs: buildUiDesignGenerationInputs(
+          normalizedPrompt,
+          dialog.uiDesignSpecReference,
+        ),
+      },
+      rememberImageModel: imageModel,
+    };
+  }
+
+  if (dialog.mode === 'publication') {
+    const workflow = getPublicationMaterialsWorkflow(
+      dialog.publicationWorkflowId ?? 'publication-cover-image',
+    );
+    const imageModel = normalizeEditorImageModel(dialog.imageModel);
+    const publicationPrompt =
+      buildPublicationMaterialsPrompt(dialog.publicationGameInfo) ||
+      normalizedPrompt;
+    const generationPrompt = buildPublicationMaterialsGenerationPrompt({
+      gameInfo: dialog.publicationGameInfo,
+      workflow,
+    });
+    return {
+      kind: 'image',
+      normalizedPrompt: publicationPrompt,
+      input: {
+        prompt: generationPrompt,
+        size: workflow.outputSize,
+        kind: 'publication-material',
+        model: imageModel,
+        aspectRatio: workflow.aspectRatio,
+        imageSize: workflow.imageSize,
+        ...(dialog.publicationReferences?.length
+          ? {
+              referenceImageSrcs: dialog.publicationReferences.map(
+                (reference) => reference.src,
+              ),
+            }
+          : {}),
+      },
+      result: {
+        title: `${nextGeneratedIndex} 宣发素材`,
+        generationInputs: buildPublicationMaterialsGenerationInputs(
+          dialog.publicationGameInfo,
+          dialog.publicationReferences,
+        ),
+      },
+      rememberImageModel: imageModel,
+    };
+  }
+
+  if (dialog.mode === 'video') {
+    const resolution = dialog.videoResolution ?? '480p';
+    const durationSeconds =
+      typeof dialog.videoDurationSeconds === 'number'
+        ? Math.min(15, Math.max(4, Math.round(dialog.videoDurationSeconds)))
+        : DEFAULT_VIDEO_DURATION_SECONDS;
+    const model = dialog.videoModel ?? DEFAULT_VIDEO_MODEL;
+    const aspectRatio = dialog.videoAspectRatio ?? DEFAULT_VIDEO_ASPECT_RATIO;
+    const sound = dialog.videoSound ?? DEFAULT_VIDEO_SOUND;
+    const webSearchEnabled =
+      dialog.videoWebSearchEnabled ?? DEFAULT_VIDEO_WEB_SEARCH_ENABLED;
+    const seedanceReferences = isSeedanceVideoModel(model)
+      ? buildSeedanceVideoReferenceInput(dialog.generationReferences ?? [])
+      : {
+          referenceImageSrcs: [],
+          referenceVideoSrcs: [],
+          referenceAudioSrcs: [],
+        };
+    return {
+      kind: 'video',
+      normalizedPrompt,
+      input: {
+        prompt: normalizedPrompt,
+        model,
+        aspectRatio,
+        durationSeconds,
+        resolution,
+        mode: 'std',
+        sound,
+        webSearchEnabled,
+        priceMudPoints: calculateEditorVideoPrice(
+          model,
+          resolution,
+          durationSeconds,
+        ),
+        ...(seedanceReferences.referenceImageSrcs.length
+          ? { referenceImageSrcs: seedanceReferences.referenceImageSrcs }
+          : {}),
+        ...(seedanceReferences.referenceVideoSrcs.length
+          ? { referenceVideoSrcs: seedanceReferences.referenceVideoSrcs }
+          : {}),
+        ...(seedanceReferences.referenceAudioSrcs.length
+          ? { referenceAudioSrcs: seedanceReferences.referenceAudioSrcs }
+          : {}),
+      },
+      result: {
+        title: `生成视频 ${nextGeneratedIndex}`,
+        generationInputs: buildVideoGenerationInputs(
+          normalizedPrompt,
+          dialog.generationReferences,
+        ),
+      },
+    };
+  }
+
+  if (dialog.mode === 'audio-sound-effect') {
+    const soundModel = dialog.soundModel ?? DEFAULT_SOUND_EFFECT_MODEL;
+    const durationSeconds =
+      typeof dialog.soundDurationSeconds === 'number'
+        ? Math.min(10, Math.max(2, Math.round(dialog.soundDurationSeconds)))
+        : DEFAULT_SOUND_EFFECT_DURATION_SECONDS;
+    return {
+      kind: 'audio',
+      audioKind: 'sound-effect',
+      normalizedPrompt,
+      input: {
+        prompt: normalizedPrompt,
+        model: soundModel,
+        duration: durationSeconds,
+        priceMudPoints: calculateEditorSoundEffectPrice(soundModel),
+      },
+      result: {
+        title: `游戏音效 ${nextGeneratedIndex}`,
+        generationInputs: buildSoundEffectGenerationInputs(
+          normalizedPrompt,
+          soundModel,
+          durationSeconds,
+        ),
+      },
+    };
+  }
+
+  if (dialog.mode === 'audio-background-music') {
+    return {
+      kind: 'audio',
+      audioKind: 'background-music',
+      normalizedPrompt,
+      input: {
+        gptDescriptionPrompt: normalizedPrompt,
+        makeInstrumental: true,
+        priceMudPoints: calculateEditorBackgroundMusicPrice(
+          DEFAULT_BACKGROUND_MUSIC_MODEL,
+        ),
+      },
+      result: {
+        title: `游戏背景音乐 ${nextGeneratedIndex}`,
+        generationInputs: buildBackgroundMusicGenerationInputs(normalizedPrompt),
+      },
+    };
+  }
+
+  const imageModel = normalizeEditorImageModel(dialog.imageModel);
+  return {
+    kind: 'image',
+    normalizedPrompt,
+    input: {
+      prompt: normalizedPrompt,
+      model: imageModel,
+      aspectRatio: dialog.aspectRatio ?? '1:1',
+      imageSize: dialog.imageSize ?? '1K',
+      ...(dialog.generationReferences?.length
+        ? {
+            referenceImageSrcs: dialog.generationReferences.map(
+              (reference) => reference.src,
+            ),
+          }
+        : {}),
+    },
+    result: {
+      title: `生成图片 ${nextGeneratedIndex}`,
+      generationInputs: buildImageGenerationInputs(
+        normalizedPrompt,
+        dialog.generationReferences,
+      ),
+    },
+    rememberImageModel: imageModel,
+  };
+}
+
+export function buildIconSpritesheetGenerationSubmissionPlan(
+  dialog: GenerateDialogState,
+): IconSpritesheetGenerationSubmissionPlan {
+  const iconDescriptions = (dialog.prompt.trim()
+    ? dialog.prompt.split(/[\r\n,，、;；/|]+/u)
+    : (dialog.iconDescriptions ?? DEFAULT_ICON_DESCRIPTIONS)
+  )
+    .map((description) => description.trim())
+    .filter(Boolean)
+    .slice(0, ICON_DESCRIPTION_LIMIT);
+
+  if (!dialog.iconSpecReference) {
+    return {
+      ok: false,
+      errorMessage: '请选择图标规范',
+    };
+  }
+
+  if (!iconDescriptions.length) {
+    return {
+      ok: false,
+      errorMessage: '请填写素材描述',
+    };
+  }
+
+  const rememberImageModel = normalizeEditorImageModel(dialog.imageModel);
+  return {
+    ok: true,
+    iconDescriptions,
+    input: {
+      referenceImageSrc: dialog.iconSpecReference.src,
+      iconDescriptions,
+      model: rememberImageModel,
+      aspectRatio: dialog.aspectRatio ?? '1:1',
+      imageSize: dialog.imageSize ?? '1K',
+      priceMudPoints: calculateEditorIconSpritesheetPrice(rememberImageModel),
+    },
+    generationInputs: buildIconGenerationInputs(
+      iconDescriptions,
+      dialog.iconSpecReference,
+    ),
+    rememberImageModel,
+  };
+}
+
+export function buildCharacterAnimationSubmissionPlan({
+  panel,
+  sourceLayer,
+}: {
+  panel: CharacterAnimationPanelState;
+  sourceLayer: CanvasLayer;
+}): CharacterAnimationSubmissionPlan {
+  const promptText = panel.promptText.trim();
+  return {
+    promptText,
+    input: {
+      sourceLayerId: sourceLayer.id,
+      sourceImageSrc: resolveCharacterAnimationSourceImageSrc(sourceLayer),
+      sourceWidth: sourceLayer.originalWidth,
+      sourceHeight: sourceLayer.originalHeight,
+      promptText,
+      resolution: panel.resolution,
+      ratio: panel.ratio,
+      frameCount: panel.frameCount,
+      durationSeconds: panel.durationSeconds,
+      priceMudPoints: calculateCharacterAnimationPrice(
+        CHARACTER_ANIMATION_MODEL,
+        panel.resolution,
+        panel.durationSeconds,
+      ),
+      model: CHARACTER_ANIMATION_MODEL,
+    },
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx
new file mode 100644
index 000000000..3f3f7ab3d
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.test.tsx
@@ -0,0 +1,222 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { createRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  GenerateDialogState,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasIconSpritesheetComposerView } from './ImageCanvasIconSpritesheetComposerView';
+
+function createIconDialog(
+  patch: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'icon',
+    prompt: '',
+    status: 'idle',
+    iconDescriptions: ['剑', '盾'],
+    imageModel: 'nanobanana2',
+    aspectRatio: '1:1',
+    imageSize: '1K',
+    ...patch,
+  };
+}
+
+function IconComposerHarness({
+  initialDialog,
+  initialMenuOpen = false,
+  onOpenSpecDialog = vi.fn(),
+  onRequestUpload = vi.fn(),
+  onUpdateIconDescriptionText = vi.fn(),
+  onRememberImageModel = vi.fn(),
+  onSubmit = vi.fn(),
+}: {
+  initialDialog: GenerateDialogState;
+  initialMenuOpen?: boolean;
+  onOpenSpecDialog?: (specType: 'character' | 'ui' | 'icon' | 'custom') => void;
+  onRequestUpload?: (target: UploadTarget) => void;
+  onUpdateIconDescriptionText?: (value: string) => void;
+  onRememberImageModel?: (model: string) => void;
+  onSubmit?: (dialog: GenerateDialogState) => void;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+  const [isMenuOpen, setIsMenuOpen] = useState(initialMenuOpen);
+  const [isPickingIconSpec, setIsPickingIconSpec] = useState(false);
+  const iconSpecButtonRef = createRef<HTMLButtonElement>();
+
+  return dialog ? (
+    <div>
+      <ImageCanvasIconSpritesheetComposerView
+        dialog={dialog}
+        style={{ left: 12, top: 24 }}
+        iconSpecButtonRef={iconSpecButtonRef}
+        isIconSpecMenuOpen={isMenuOpen}
+        setGenerateDialog={setDialog}
+        setIsIconSpecMenuOpen={setIsMenuOpen}
+        setIsPickingIconSpecFromCanvas={setIsPickingIconSpec}
+        renderEditorPortal={(node) => node}
+        buildPortalMenuStyle={() => ({ position: 'fixed', left: 0, top: 0 })}
+        onOpenSpecDialog={onOpenSpecDialog}
+        onRequestUpload={onRequestUpload}
+        onUpdateIconDescriptionText={onUpdateIconDescriptionText}
+        onRememberImageModel={onRememberImageModel}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="当前菜单">{String(isMenuOpen)}</output>
+      <output aria-label="正在选择图标规范">{String(isPickingIconSpec)}</output>
+      <output aria-label="当前模型">{dialog.imageModel}</output>
+      <output aria-label="当前尺寸">{dialog.imageSize}</output>
+    </div>
+  ) : null;
+}
+
+describe('ImageCanvasIconSpritesheetComposerView', () => {
+  it('opens icon spec menu and supports each source action', () => {
+    const openSpecDialog = vi.fn();
+    const requestUpload = vi.fn();
+    render(
+      <IconComposerHarness
+        initialDialog={createIconDialog()}
+        onOpenSpecDialog={openSpecDialog}
+        onRequestUpload={requestUpload}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '图标规范' }));
+    expect(screen.getByRole('menu', { name: '图标规范来源' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+    expect(screen.getByLabelText('正在选择图标规范').textContent).toBe('true');
+    expect(screen.getByLabelText('当前菜单').textContent).toBe('false');
+
+    fireEvent.click(screen.getByRole('button', { name: '图标规范' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '新建图标规范' }));
+    expect(openSpecDialog).toHaveBeenCalledWith('icon');
+
+    fireEvent.click(screen.getByRole('button', { name: '图标规范' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+    expect(requestUpload).toHaveBeenCalledWith('icon-spec');
+  });
+
+  it('keeps the spec reference as a single first-row card without extra source buttons', () => {
+    render(<IconComposerHarness initialDialog={createIconDialog()} />);
+
+    const panel = screen.getByRole('dialog', { name: '生成图标素材' });
+    const firstRow = panel.querySelector('.image-canvas-editor__reference-strip');
+
+    expect(firstRow).toBeTruthy();
+    expect(
+      within(firstRow as HTMLElement).getByRole('button', {
+        name: '图标规范',
+      }),
+    ).toBeTruthy();
+    expect(
+      panel.querySelector('.image-canvas-editor__icon-spec-actions'),
+    ).toBeNull();
+    expect(screen.queryByRole('button', { name: '画布' })).toBeNull();
+    expect(screen.queryByRole('button', { name: '新建' })).toBeNull();
+    expect(screen.queryByRole('button', { name: '上传' })).toBeNull();
+  });
+
+  it('removes a bound icon spec from the hover delete button', () => {
+    render(
+      <IconComposerHarness
+        initialDialog={createIconDialog({
+          iconSpecReference: {
+            id: 'icon-spec-a',
+            label: '图标规范A',
+            src: 'data:image/png;base64,aWNvbg==',
+          },
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '删除图标规范' }));
+
+    expect(screen.getByRole('button', { name: '图标规范' })).toBeTruthy();
+    expect(screen.queryByRole('button', { name: '图标规范A' })).toBeNull();
+  });
+
+  it('updates multi-line descriptions and submits', () => {
+    const updateIconDescriptionText = vi.fn();
+    const submitIconGeneration = vi.fn();
+    const dialog = createIconDialog({ prompt: '剑\n盾' });
+    render(
+      <IconComposerHarness
+        initialDialog={dialog}
+        onUpdateIconDescriptionText={updateIconDescriptionText}
+        onSubmit={submitIconGeneration}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('素材描述'), {
+      target: { value: '魔法剑\n圆盾' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect(updateIconDescriptionText).toHaveBeenCalledWith('魔法剑\n圆盾');
+    expect(submitIconGeneration).toHaveBeenCalledWith(dialog);
+  });
+
+  it('keeps image option changes inside the icon dialog', () => {
+    const rememberImageModel = vi.fn();
+    render(
+      <IconComposerHarness
+        initialDialog={createIconDialog({
+          imageModel: 'nanobanana2',
+          imageSize: '0.5K',
+        })}
+        onRememberImageModel={rememberImageModel}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '生成图片模型 nanobanana2' }),
+    );
+    const modelPanel = screen.getByRole('menu', { name: '生成图片模型选项' });
+    fireEvent.click(
+      within(modelPanel).getByRole('button', { name: 'gpt-image-2' }),
+    );
+
+    expect(rememberImageModel).toHaveBeenCalledWith('gpt-image-2');
+    expect(screen.getByLabelText('当前模型').textContent).toBe('gpt-image-2');
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('1K');
+    expect(screen.getByRole('button', { name: '生成' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('disables generation controls and renders failure state', () => {
+    const submitIconGeneration = vi.fn();
+    const { rerender } = render(
+      <IconComposerHarness
+        initialDialog={createIconDialog({ status: 'generating' })}
+        onSubmit={submitIconGeneration}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect((screen.getByLabelText('素材描述') as HTMLInputElement).disabled).toBe(
+      true,
+    );
+    expect(submitIconGeneration).not.toHaveBeenCalled();
+
+    rerender(
+      <IconComposerHarness
+        key="failed"
+        initialDialog={createIconDialog({
+          status: 'failed',
+          errorMessage: '生成失败',
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('alert').textContent).toContain('生成失败');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx
new file mode 100644
index 000000000..42c5d035a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasIconSpritesheetComposerView.tsx
@@ -0,0 +1,212 @@
+import { ImageIcon } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import type {
+  GenerateDialogState,
+  SpecGenerationType,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import {
+  calculateEditorIconSpritesheetPrice,
+  DEFAULT_ICON_DESCRIPTIONS,
+} from './ImageCanvasGenerationModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasIconSpritesheetComposerViewProps = {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  iconSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  isIconSpecMenuOpen: boolean;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setIsIconSpecMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPickingIconSpecFromCanvas: Dispatch<SetStateAction<boolean>>;
+  renderEditorPortal: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onOpenSpecDialog: (specType: SpecGenerationType) => void;
+  onRequestUpload: (target: UploadTarget) => void;
+  onUpdateIconDescriptionText: (value: string) => void;
+  onRememberImageModel: (model: string) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+
+export function ImageCanvasIconSpritesheetComposerView({
+  dialog,
+  style,
+  iconSpecButtonRef,
+  isIconSpecMenuOpen,
+  setGenerateDialog,
+  setIsIconSpecMenuOpen,
+  setIsPickingIconSpecFromCanvas,
+  renderEditorPortal,
+  buildPortalMenuStyle,
+  onOpenSpecDialog,
+  onRequestUpload,
+  onUpdateIconDescriptionText,
+  onRememberImageModel,
+  onSubmit,
+}: ImageCanvasIconSpritesheetComposerViewProps) {
+  const descriptionText =
+    dialog.prompt ||
+    (dialog.iconDescriptions ?? DEFAULT_ICON_DESCRIPTIONS).join('\n');
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isIconSpecMenuOpen,
+    boundaryRefs: [iconSpecButtonRef],
+    onDismiss: () => setIsIconSpecMenuOpen(false),
+  });
+
+  const pickIconSpecFromCanvas = () => {
+    setIsPickingIconSpecFromCanvas(true);
+    setIsIconSpecMenuOpen(false);
+  };
+
+  const openIconSpecDialog = () => {
+    setIsIconSpecMenuOpen(false);
+    onOpenSpecDialog('icon');
+  };
+
+  const requestIconSpecUpload = () => {
+    setIsIconSpecMenuOpen(false);
+    onRequestUpload('icon-spec');
+  };
+
+  return (
+    <form
+      className="image-canvas-editor__icon-composer"
+      style={style}
+      role="dialog"
+      aria-label="生成图标素材"
+      onPointerDown={(event) => event.stopPropagation()}
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (dialog.status !== 'generating') {
+          onSubmit({ ...dialog, prompt: descriptionText });
+        }
+      }}
+    >
+      <div className="image-canvas-editor__reference-strip">
+        <ImageCanvasReferenceSlot
+          buttonRef={iconSpecButtonRef}
+          tone="icon"
+          className="image-canvas-editor__icon-spec-card"
+          icon={<ImageIcon className="h-4 w-4" aria-hidden="true" />}
+          imageSrc={dialog.iconSpecReference?.src}
+          label="图标规范"
+          ariaLabel={dialog.iconSpecReference?.label ?? '图标规范'}
+          title={dialog.iconSpecReference?.label ?? '图标规范'}
+          disabled={dialog.status === 'generating'}
+          isAdd={!dialog.iconSpecReference}
+          onClick={() => setIsIconSpecMenuOpen((open) => !open)}
+          onRemove={
+            dialog.iconSpecReference
+              ? () =>
+                  setGenerateDialog((currentDialog) =>
+                    currentDialog?.mode === 'icon'
+                      ? {
+                          ...currentDialog,
+                          status:
+                            currentDialog.status === 'failed'
+                              ? 'idle'
+                              : currentDialog.status,
+                          errorMessage:
+                            currentDialog.status === 'failed'
+                              ? undefined
+                              : currentDialog.errorMessage,
+                          iconSpecReference: null,
+                        }
+                      : currentDialog,
+                  )
+              : undefined
+          }
+          removeLabel="删除图标规范"
+        />
+        {isIconSpecMenuOpen
+          ? renderEditorPortal(
+              <PlatformFloatingMenu
+                className="image-canvas-editor__character-spec-menu image-canvas-editor__portal-menu"
+                label="图标规范来源"
+                placement="top-start"
+                style={buildPortalMenuStyle(
+                  iconSpecButtonRef.current,
+                  'above',
+                )}
+              >
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={pickIconSpecFromCanvas}
+                >
+                  从画布中选择
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={openIconSpecDialog}
+                >
+                  新建图标规范
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={requestIconSpecUpload}
+                >
+                  上传图片
+                </PlatformFloatingMenuItem>
+              </PlatformFloatingMenu>,
+            )
+          : null}
+      </div>
+      <label className="image-canvas-editor__field-block image-canvas-editor__field-block--single">
+        <PlatformTextField
+          variant="textarea"
+          aria-label="素材描述"
+          value={descriptionText}
+          disabled={dialog.status === 'generating'}
+          placeholder="描述要生成的多个素材，每行一个。"
+          size="sm"
+          density="compact"
+          className="image-canvas-editor__generation-prompt image-canvas-editor__generation-prompt--borderless"
+          onChange={(event) => onUpdateIconDescriptionText(event.target.value)}
+        />
+      </label>
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+      <div className="image-canvas-editor__generation-composer-footer">
+        <ImageCanvasGenerationImageOptionsView
+          dialog={dialog}
+          setGenerateDialog={setGenerateDialog}
+          includeDimensions
+          onRememberImageModel={onRememberImageModel}
+          optionLabelPrefix="生成图片"
+          cost={calculateEditorIconSpritesheetPrice(dialog.imageModel)}
+          submitLabel="生成"
+          submitAriaLabel="生成"
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+        />
+      </div>
+    </form>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasInteractionModel.test.ts b/src/components/image-editor/ImageCanvasInteractionModel.test.ts
new file mode 100644
index 000000000..d461ca4cc
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasInteractionModel.test.ts
@@ -0,0 +1,435 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createMinimapModel,
+  fitViewportToLayers,
+  getCanvasDropPoint,
+  getCanvasPointFromClient,
+  getWorldPointFromClient,
+  moveGenerationFrameFromDrag,
+  moveGenerationFramesFromDrag,
+  moveDragSelectedLayers,
+  moveLayersFromDrag,
+  moveViewportFromMinimapDrag,
+  moveViewportFromMinimapPointer,
+  moveViewportFromPan,
+  scaleViewportFromScreenPoint,
+  scrollViewportVertically,
+  selectCanvasObjectsInsideMarquee,
+  selectLayersInsideMarquee,
+  zoomViewportFromWheel,
+} from './ImageCanvasInteractionModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  DragState,
+} from './ImageCanvasEditorTypes';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+
+function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 120,
+    width: 200,
+    height: 100,
+    originalWidth: 200,
+    originalHeight: 100,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createGenerationDialog(
+  overrides: Partial<CanvasGenerationDialogState> = {},
+): CanvasGenerationDialogState {
+  const id = overrides.id ?? 'dialog-a';
+  return {
+    id,
+    mode: 'generate',
+    prompt: id,
+    status: 'idle',
+    placeholder: {
+      x: 100,
+      y: 120,
+      width: 200,
+      height: 100,
+      originalWidth: 200,
+      originalHeight: 100,
+    },
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasInteractionModel', () => {
+  it('fits layers into the visible canvas without upscaling past 100%', () => {
+    const viewport = fitViewportToLayers({
+      layers: [
+        createLayer({ id: 'left', x: 0, y: 0, width: 400, height: 300 }),
+        createLayer({ id: 'right', x: 600, y: 100, width: 200, height: 200 }),
+      ],
+      canvasSize: { width: 900, height: 640 },
+    });
+
+    expect(viewport).toEqual({
+      x: 50,
+      y: 170,
+      scale: 1,
+    });
+
+    expect(
+      fitViewportToLayers({
+        layers: [createLayer({ width: 5000, height: 3000 })],
+        canvasSize: { width: 900, height: 640 },
+      })?.scale,
+    ).toBe(0.24);
+  });
+
+  it('maps client points to canvas and world coordinates with safe fallbacks', () => {
+    const rect = { left: 100, top: 50, right: 700, bottom: 450 };
+
+    expect(
+      getCanvasPointFromClient({ clientX: 260, clientY: 190, rect }),
+    ).toEqual({ x: 160, y: 140 });
+    expect(
+      getCanvasPointFromClient({ clientX: 80, clientY: 190, rect }),
+    ).toBeNull();
+    expect(
+      getCanvasDropPoint({
+        clientX: 80,
+        clientY: 190,
+        rect,
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ x: 450, y: 320 });
+    expect(
+      getWorldPointFromClient({
+        clientX: 260,
+        clientY: 190,
+        rect,
+        viewport: { x: -40, y: 20, scale: 2 },
+      }),
+    ).toEqual({ x: 100, y: 60 });
+  });
+
+  it('scrolls vertically and zooms around a screen point', () => {
+    const viewport = { x: 10, y: 20, scale: 1 };
+
+    expect(scrollViewportVertically(viewport, 120)).toEqual({
+      x: 10,
+      y: -100,
+      scale: 1,
+    });
+
+    expect(
+      scaleViewportFromScreenPoint({
+        viewport,
+        nextScale: 2,
+        screenPoint: { x: 210, y: 120 },
+      }),
+    ).toEqual({ x: -190, y: -80, scale: 2 });
+
+    const zoomedViewport = zoomViewportFromWheel({
+      viewport,
+      deltaY: -120,
+      screenPoint: { x: 210, y: 120 },
+    });
+    expect(zoomedViewport.x).toBeCloseTo(-10);
+    expect(zoomedViewport.y).toBeCloseTo(10);
+    expect(zoomedViewport.scale).toBe(1.1);
+  });
+
+  it('selects layers intersecting the marquee in screen space', () => {
+    const selectedIds = selectLayersInsideMarquee({
+      marquee: {
+        pointerId: 1,
+        startX: 90,
+        startY: 90,
+        currentX: 90,
+        currentY: 90,
+      },
+      currentPoint: { x: 360, y: 260 },
+      viewport: { x: 20, y: 10, scale: 1 },
+      layers: [
+        createLayer({ id: 'inside', x: 100, y: 120 }),
+        createLayer({ id: 'outside', x: 600, y: 600 }),
+      ],
+    });
+
+    expect(selectedIds).toEqual(['inside']);
+    expect(
+      selectCanvasObjectsInsideMarquee({
+        marquee: {
+          pointerId: 1,
+          startX: 90,
+          startY: 90,
+          currentX: 90,
+          currentY: 90,
+        },
+        currentPoint: { x: 360, y: 260 },
+        viewport: { x: 20, y: 10, scale: 1 },
+        layers: [createLayer({ id: 'inside', x: 100, y: 120 })],
+        generationDialogs: [
+          createGenerationDialog({
+            id: 'dialog-inside',
+            placeholder: {
+              x: 130,
+              y: 130,
+              width: 80,
+              height: 80,
+              originalWidth: 80,
+              originalHeight: 80,
+            },
+          }),
+          createGenerationDialog({
+            id: 'dialog-outside',
+            placeholder: {
+              x: 900,
+              y: 900,
+              width: 80,
+              height: 80,
+              originalWidth: 80,
+              originalHeight: 80,
+            },
+          }),
+        ],
+      }),
+    ).toEqual(['inside', getCanvasGenerationSelectionId('dialog-inside')]);
+  });
+
+  it('moves pan, generation frames, and layer groups from drag state', () => {
+    expect(
+      moveViewportFromPan(
+        {
+          kind: 'pan',
+          pointerId: 1,
+          startClientX: 100,
+          startClientY: 200,
+          startViewport: { x: 10, y: 20, scale: 1 },
+        },
+        { x: 140, y: 170 },
+      ),
+    ).toEqual({ x: 50, y: -10, scale: 1 });
+
+    expect(
+      moveGenerationFrameFromDrag(
+        {
+          kind: 'generation-frame',
+          dialogId: 'dialog-1',
+          dialogIds: ['dialog-1'],
+          layerIds: [],
+          pointerId: 1,
+          startClientX: 100,
+          startClientY: 200,
+          startFrameX: 300,
+          startFrameY: 400,
+          startFrames: [{ id: 'dialog-1', x: 300, y: 400 }],
+          startLayers: [],
+          startScale: 2,
+        },
+        { x: 140, y: 170 },
+      ),
+    ).toEqual({ x: 320, y: 385 });
+
+    const layers = [
+      createLayer({ id: 'moving', x: 90, y: 90, width: 100, height: 100 }),
+      createLayer({ id: 'follower', x: 220, y: 90, width: 100, height: 100 }),
+      createLayer({ id: 'anchor', x: 300, y: 100, width: 100, height: 100 }),
+    ];
+    const result = moveLayersFromDrag({
+      layers,
+      pointer: { x: 210, y: 100 },
+      dragState: {
+        kind: 'layer',
+        pointerId: 1,
+        layerId: 'moving',
+        layerIds: ['moving', 'follower'],
+        startClientX: 100,
+        startClientY: 100,
+        startLayerX: 90,
+        startLayerY: 90,
+        startLayers: [
+          { id: 'moving', x: 90, y: 90 },
+          { id: 'follower', x: 220, y: 90 },
+        ],
+        startScale: 1,
+      },
+    });
+
+    expect(result?.layers.find((layer) => layer.id === 'moving')).toMatchObject({
+      x: 200,
+      y: 100,
+    });
+    expect(result?.layers.find((layer) => layer.id === 'follower')).toMatchObject({
+      x: 330,
+      y: 100,
+    });
+    expect(result?.snapGuide).toEqual({
+      vertical: 300,
+      horizontal: 100,
+    });
+    expect(result?.snapOffset).toEqual({
+      x: 0,
+      y: 10,
+    });
+
+    const generationDialogs = [
+      createGenerationDialog({ id: 'dialog-1' }),
+      createGenerationDialog({
+        id: 'dialog-2',
+        placeholder: {
+          x: 400,
+          y: 120,
+          width: 200,
+          height: 100,
+          originalWidth: 200,
+          originalHeight: 100,
+        },
+      }),
+    ];
+    expect(
+      moveGenerationFramesFromDrag({
+        generationDialogs,
+        pointer: { x: 140, y: 170 },
+        snapOffset: { x: 6, y: -4 },
+        dragState: {
+          kind: 'generation-frame',
+          dialogId: 'dialog-1',
+          dialogIds: ['dialog-1', 'dialog-2'],
+          layerIds: ['moving'],
+          pointerId: 1,
+          startClientX: 100,
+          startClientY: 200,
+          startFrameX: 100,
+          startFrameY: 120,
+          startFrames: [
+            { id: 'dialog-1', x: 100, y: 120 },
+            { id: 'dialog-2', x: 400, y: 120 },
+          ],
+          startLayers: [{ id: 'moving', x: 90, y: 90 }],
+          startScale: 2,
+        },
+      }).generationDialogs.map((dialog) => [
+        dialog.id,
+        dialog.placeholder?.x,
+        dialog.placeholder?.y,
+      ]),
+    ).toEqual([
+      ['dialog-1', 126, 101],
+      ['dialog-2', 426, 101],
+    ]);
+    expect(
+      moveDragSelectedLayers({
+        layers,
+        pointer: { x: 140, y: 170 },
+        snapOffset: { x: 6, y: -4 },
+        dragState: {
+          kind: 'generation-frame',
+          dialogId: 'dialog-1',
+          dialogIds: ['dialog-1'],
+          layerIds: ['moving'],
+          pointerId: 1,
+          startClientX: 100,
+          startClientY: 200,
+          startFrameX: 100,
+          startFrameY: 120,
+          startFrames: [{ id: 'dialog-1', x: 100, y: 120 }],
+          startLayers: [{ id: 'moving', x: 90, y: 90 }],
+          startScale: 2,
+        },
+      }).find((layer) => layer.id === 'moving'),
+    ).toMatchObject({ x: 116, y: 71 });
+  });
+
+  it('snaps generation frames to nearby layer guides while dragging', () => {
+    const [anchorLayer] = [
+      createLayer({ id: 'anchor', x: 420, y: 300, width: 120, height: 100 }),
+    ];
+    const [movingDialog] = [
+      createGenerationDialog({
+        id: 'dialog-moving',
+        placeholder: {
+          x: 100,
+          y: 120,
+          width: 120,
+          height: 100,
+          originalWidth: 120,
+          originalHeight: 100,
+        },
+      }),
+    ];
+    const result = moveGenerationFramesFromDrag({
+      layers: [anchorLayer],
+      generationDialogs: [movingDialog],
+      pointer: { x: 414, y: 292 },
+      dragState: {
+        kind: 'generation-frame',
+        dialogId: 'dialog-moving',
+        dialogIds: ['dialog-moving'],
+        layerIds: [],
+        pointerId: 1,
+        startClientX: 100,
+        startClientY: 120,
+        startFrameX: 100,
+        startFrameY: 120,
+        startFrames: [{ id: 'dialog-moving', x: 100, y: 120 }],
+        startLayers: [],
+        startScale: 1,
+      },
+    });
+
+    expect(result.generationDialogs[0]?.placeholder).toMatchObject({
+      x: 420,
+      y: 300,
+    });
+    expect(result.snapGuide).toEqual({
+      vertical: 420,
+      horizontal: 300,
+    });
+  });
+
+  it('builds minimap projection and moves the viewport from minimap interactions', () => {
+    const layers = [
+      createLayer({ id: 'one', x: 100, y: 100, width: 200, height: 100 }),
+      createLayer({ id: 'two', x: 700, y: 400, width: 100, height: 100 }),
+    ];
+    const minimap = createMinimapModel({
+      layers,
+      viewport: { x: -100, y: -50, scale: 1 },
+      canvasSize: { width: 900, height: 640 },
+    });
+
+    expect(minimap?.layers).toHaveLength(2);
+    expect(minimap?.viewport.width).toBeGreaterThan(2);
+
+    const nextViewport = moveViewportFromMinimapPointer({
+      viewport: { x: -100, y: -50, scale: 1 },
+      canvasSize: { width: 900, height: 640 },
+      minimapModel: minimap!,
+      pointer: { x: 100, y: 66 },
+    });
+    expect(nextViewport.x).not.toBe(-100);
+    expect(nextViewport.y).not.toBe(-50);
+
+    const dragState: Extract<DragState, { kind: 'minimap' }> = {
+      kind: 'minimap',
+      pointerId: 1,
+      startClientX: 100,
+      startClientY: 100,
+      startViewport: { x: -100, y: -50, scale: 1 },
+      minimapScale: minimap!.scale,
+      moved: true,
+    };
+    const draggedViewport = moveViewportFromMinimapDrag(dragState, {
+      x: 103,
+      y: 102,
+    });
+    expect(draggedViewport.x).toBeLessThan(-100);
+    expect(draggedViewport.y).toBeLessThan(-50);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasInteractionModel.ts b/src/components/image-editor/ImageCanvasInteractionModel.ts
new file mode 100644
index 000000000..692210672
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasInteractionModel.ts
@@ -0,0 +1,692 @@
+import type { CSSProperties } from 'react';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasViewport,
+  DragState,
+} from './ImageCanvasEditorTypes';
+import {
+  DEFAULT_CANVAS_SIZE,
+  FIT_VIEW_PADDING,
+  MAX_SCALE,
+  MIN_SCALE,
+  MINIMAP_DRAG_SENSITIVITY,
+  MINIMAP_PADDING,
+  MINIMAP_SIZE,
+  clamp,
+  getLayerBounds,
+  resolveSnappedItemPosition,
+} from './ImageCanvasEditorModel';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+
+export type CanvasSize = {
+  width: number;
+  height: number;
+};
+
+export type CanvasPoint = {
+  x: number;
+  y: number;
+};
+
+export type CanvasRect = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+};
+
+export type CanvasLayerMoveResult = {
+  layers: CanvasLayer[];
+  snapGuide: ReturnType<typeof resolveSnappedItemPosition>['guide'];
+  snapOffset: CanvasPoint;
+};
+
+export type CanvasGenerationFrameMoveResult = {
+  generationDialogs: CanvasGenerationDialogState[];
+  snapGuide: ReturnType<typeof resolveSnappedItemPosition>['guide'];
+  snapOffset: CanvasPoint;
+};
+
+export type StageMinimapModel = {
+  bounds: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+  };
+  scale: number;
+  layers: Array<{
+    id: string;
+    title: string;
+    rect: CSSProperties;
+  }>;
+  viewport: CSSProperties;
+};
+
+export function getCanvasPointFromClient({
+  clientX,
+  clientY,
+  rect,
+}: {
+  clientX: number;
+  clientY: number;
+  rect: CanvasRect | null;
+}): CanvasPoint | null {
+  if (!rect) {
+    return null;
+  }
+  if (
+    clientX < rect.left ||
+    clientX > rect.right ||
+    clientY < rect.top ||
+    clientY > rect.bottom
+  ) {
+    return null;
+  }
+  return {
+    x: clientX - rect.left,
+    y: clientY - rect.top,
+  };
+}
+
+export function getCanvasDropPoint({
+  clientX,
+  clientY,
+  rect,
+  canvasSize,
+}: {
+  clientX: number;
+  clientY: number;
+  rect: CanvasRect | null;
+  canvasSize: CanvasSize;
+}) {
+  return (
+    getCanvasPointFromClient({ clientX, clientY, rect }) ?? {
+      x: Number.isFinite(canvasSize.width) ? canvasSize.width / 2 : 0,
+      y: Number.isFinite(canvasSize.height) ? canvasSize.height / 2 : 0,
+    }
+  );
+}
+
+export function getWorldPointFromClient({
+  clientX,
+  clientY,
+  rect,
+  viewport,
+}: {
+  clientX: number;
+  clientY: number;
+  rect: CanvasRect | null;
+  viewport: CanvasViewport;
+}) {
+  const screenX = clientX - (rect?.left ?? 0);
+  const screenY = clientY - (rect?.top ?? 0);
+  return {
+    x: (screenX - viewport.x) / viewport.scale,
+    y: (screenY - viewport.y) / viewport.scale,
+  };
+}
+
+export function fitViewportToLayers({
+  layers,
+  canvasSize,
+}: {
+  layers: CanvasLayer[];
+  canvasSize: CanvasSize;
+}): CanvasViewport | null {
+  const bounds = getLayerBounds(layers);
+  if (!bounds) {
+    return null;
+  }
+  const boundsWidth = Math.max(1, bounds.maxX - bounds.minX);
+  const boundsHeight = Math.max(1, bounds.maxY - bounds.minY);
+  const availableWidth = Math.max(1, canvasSize.width - FIT_VIEW_PADDING * 2);
+  const availableHeight = Math.max(1, canvasSize.height - FIT_VIEW_PADDING * 2);
+  const scale = clamp(
+    Math.min(1, availableWidth / boundsWidth, availableHeight / boundsHeight),
+    MIN_SCALE,
+    MAX_SCALE,
+  );
+
+  return {
+    x: canvasSize.width / 2 - (bounds.minX + boundsWidth / 2) * scale,
+    y: canvasSize.height / 2 - (bounds.minY + boundsHeight / 2) * scale,
+    scale,
+  };
+}
+
+export function scaleViewportFromScreenPoint({
+  viewport,
+  nextScale,
+  screenPoint,
+}: {
+  viewport: CanvasViewport;
+  nextScale: number;
+  screenPoint: CanvasPoint | null;
+}) {
+  const scale = clamp(nextScale, MIN_SCALE, MAX_SCALE);
+  if (!screenPoint) {
+    return {
+      ...viewport,
+      scale,
+    };
+  }
+  const worldX = (screenPoint.x - viewport.x) / viewport.scale;
+  const worldY = (screenPoint.y - viewport.y) / viewport.scale;
+  return {
+    x: screenPoint.x - worldX * scale,
+    y: screenPoint.y - worldY * scale,
+    scale,
+  };
+}
+
+export function scrollViewportVertically(
+  viewport: CanvasViewport,
+  deltaY: number,
+) {
+  return {
+    ...viewport,
+    y: viewport.y - deltaY,
+  };
+}
+
+export function zoomViewportFromWheel({
+  viewport,
+  deltaY,
+  screenPoint,
+}: {
+  viewport: CanvasViewport;
+  deltaY: number;
+  screenPoint: CanvasPoint;
+}) {
+  return scaleViewportFromScreenPoint({
+    viewport,
+    nextScale: viewport.scale * (deltaY > 0 ? 0.9 : 1.1),
+    screenPoint,
+  });
+}
+
+export function moveViewportFromPan(
+  dragState: Extract<DragState, { kind: 'pan' }>,
+  pointer: CanvasPoint,
+) {
+  return {
+    ...dragState.startViewport,
+    x: dragState.startViewport.x + pointer.x - dragState.startClientX,
+    y: dragState.startViewport.y + pointer.y - dragState.startClientY,
+  };
+}
+
+export function moveGenerationFrameFromDrag(
+  dragState: Extract<DragState, { kind: 'generation-frame' }>,
+  pointer: CanvasPoint,
+) {
+  return {
+    x:
+      dragState.startFrameX +
+      (pointer.x - dragState.startClientX) / dragState.startScale,
+    y:
+      dragState.startFrameY +
+      (pointer.y - dragState.startClientY) / dragState.startScale,
+  };
+}
+
+function getMarqueeRect({
+  marquee,
+  currentPoint,
+}: {
+  marquee: CanvasMarqueeState;
+  currentPoint: CanvasPoint;
+}) {
+  return {
+    left: Math.min(marquee.startX, currentPoint.x),
+    right: Math.max(marquee.startX, currentPoint.x),
+    top: Math.min(marquee.startY, currentPoint.y),
+    bottom: Math.max(marquee.startY, currentPoint.y),
+  };
+}
+
+function intersectsScreenRect({
+  x,
+  y,
+  width,
+  height,
+  viewport,
+  rect,
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  viewport: CanvasViewport;
+  rect: { left: number; right: number; top: number; bottom: number };
+}) {
+  const itemLeft = viewport.x + x * viewport.scale;
+  const itemTop = viewport.y + y * viewport.scale;
+  const itemRight = itemLeft + width * viewport.scale;
+  const itemBottom = itemTop + height * viewport.scale;
+  return (
+    itemLeft <= rect.right &&
+    itemRight >= rect.left &&
+    itemTop <= rect.bottom &&
+    itemBottom >= rect.top
+  );
+}
+
+function getCanvasSnapItems({
+  layers,
+  generationDialogs,
+  excludedLayerIds = [],
+  excludedGenerationDialogIds = [],
+}: {
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+  excludedLayerIds?: string[];
+  excludedGenerationDialogIds?: string[];
+}) {
+  const layerSnapItems = layers
+    .filter((layer) => !excludedLayerIds.includes(layer.id))
+    .map((layer) => ({
+      id: layer.id,
+      x: layer.x,
+      y: layer.y,
+      width: layer.width,
+      height: layer.height,
+      hidden: layer.hidden,
+    }));
+  const generationSnapItems = generationDialogs.flatMap((dialog) => {
+    if (
+      !dialog.placeholder ||
+      excludedGenerationDialogIds.includes(dialog.id)
+    ) {
+      return [];
+    }
+    return [
+      {
+        id: getCanvasGenerationSelectionId(dialog.id),
+        x: dialog.placeholder.x,
+        y: dialog.placeholder.y,
+        width: dialog.placeholder.width,
+        height: dialog.placeholder.height,
+      },
+    ];
+  });
+  return [...layerSnapItems, ...generationSnapItems];
+}
+
+export function selectLayersInsideMarquee({
+  marquee,
+  currentPoint,
+  layers,
+  viewport,
+}: {
+  marquee: CanvasMarqueeState;
+  currentPoint: CanvasPoint;
+  layers: CanvasLayer[];
+  viewport: CanvasViewport;
+}) {
+  const rect = getMarqueeRect({ marquee, currentPoint });
+
+  return layers
+    .filter((layer) => {
+      return intersectsScreenRect({
+        x: layer.x,
+        y: layer.y,
+        width: layer.width,
+        height: layer.height,
+        viewport,
+        rect,
+      });
+    })
+    .map((layer) => layer.id);
+}
+
+export function selectCanvasObjectsInsideMarquee({
+  marquee,
+  currentPoint,
+  layers,
+  generationDialogs,
+  viewport,
+}: {
+  marquee: CanvasMarqueeState;
+  currentPoint: CanvasPoint;
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+  viewport: CanvasViewport;
+}) {
+  const rect = getMarqueeRect({ marquee, currentPoint });
+  const layerIds = selectLayersInsideMarquee({
+    marquee,
+    currentPoint,
+    layers,
+    viewport,
+  });
+  const generationDialogIds = generationDialogs
+    .filter((dialog) => {
+      const placeholder = dialog.placeholder;
+      if (!placeholder) {
+        return false;
+      }
+      return intersectsScreenRect({
+        x: placeholder.x,
+        y: placeholder.y,
+        width: placeholder.width,
+        height: placeholder.height,
+        viewport,
+        rect,
+      });
+    })
+    .map((dialog) => getCanvasGenerationSelectionId(dialog.id));
+  return [...layerIds, ...generationDialogIds];
+}
+
+export function moveLayersFromDrag({
+  dragState,
+  layers,
+  generationDialogs = [],
+  pointer,
+}: {
+  dragState: Extract<DragState, { kind: 'layer' }>;
+  layers: CanvasLayer[];
+  generationDialogs?: CanvasGenerationDialogState[];
+  pointer: CanvasPoint;
+}): CanvasLayerMoveResult | null {
+  const movingLayer = layers.find((layer) => layer.id === dragState.layerId);
+  if (!movingLayer) {
+    return null;
+  }
+  const deltaX = (pointer.x - dragState.startClientX) / dragState.startScale;
+  const deltaY = (pointer.y - dragState.startClientY) / dragState.startScale;
+  const proposedX = dragState.startLayerX + deltaX;
+  const proposedY = dragState.startLayerY + deltaY;
+  const snapped = resolveSnappedItemPosition(
+    movingLayer,
+    proposedX,
+    proposedY,
+    getCanvasSnapItems({
+      layers,
+      generationDialogs,
+      excludedLayerIds: dragState.layerIds,
+      excludedGenerationDialogIds: dragState.generationDialogIds ?? [],
+    }),
+    dragState.startScale,
+  );
+  const snapOffset = {
+    x: snapped.x - proposedX,
+    y: snapped.y - proposedY,
+  };
+
+  return {
+    snapGuide: snapped.guide,
+    snapOffset,
+    layers: layers.map((layer) =>
+      dragState.layerIds.includes(layer.id)
+        ? (() => {
+            const startLayer = dragState.startLayers.find(
+              (item) => item.id === layer.id,
+            );
+            if (!startLayer) {
+              return layer;
+            }
+            if (layer.id === dragState.layerId) {
+              return {
+                ...layer,
+                x: snapped.x,
+                y: snapped.y,
+              };
+            }
+            return {
+              ...layer,
+              x: startLayer.x + deltaX + (snapped.x - proposedX),
+              y: startLayer.y + deltaY + (snapped.y - proposedY),
+            };
+          })()
+        : layer,
+    ),
+  };
+}
+
+export function moveGenerationFramesFromDrag({
+  dragState,
+  generationDialogs,
+  layers = [],
+  snapOffset,
+  pointer,
+}: {
+  dragState: Extract<DragState, { kind: 'layer' | 'generation-frame' }>;
+  generationDialogs: CanvasGenerationDialogState[];
+  layers?: CanvasLayer[];
+  snapOffset?: CanvasPoint | null;
+  pointer: CanvasPoint;
+}): CanvasGenerationFrameMoveResult {
+  const deltaX = (pointer.x - dragState.startClientX) / dragState.startScale;
+  const deltaY = (pointer.y - dragState.startClientY) / dragState.startScale;
+  const targetDialogIds =
+    dragState.kind === 'generation-frame'
+      ? dragState.dialogIds
+      : (dragState.generationDialogIds ?? []);
+  if (!targetDialogIds.length) {
+    return {
+      generationDialogs,
+      snapGuide: null,
+      snapOffset: { x: 0, y: 0 },
+    };
+  }
+  const startFrames =
+    dragState.kind === 'generation-frame'
+      ? dragState.startFrames
+      : (dragState.startGenerationFrames ?? []);
+  const movingDialogId =
+    dragState.kind === 'generation-frame'
+      ? dragState.dialogId
+      : targetDialogIds[0];
+  const movingDialog = generationDialogs.find(
+    (dialog) => dialog.id === movingDialogId,
+  );
+  const movingPlaceholder = movingDialog?.placeholder;
+  const movingStartFrame = startFrames.find(
+    (frame) => frame.id === movingDialogId,
+  );
+  const proposedX = (movingStartFrame?.x ?? 0) + deltaX;
+  const proposedY = (movingStartFrame?.y ?? 0) + deltaY;
+  const snapped =
+    snapOffset || dragState.kind === 'layer'
+      ? {
+          x: proposedX + (snapOffset?.x ?? 0),
+          y: proposedY + (snapOffset?.y ?? 0),
+          guide: null,
+        }
+      : movingDialog && movingPlaceholder && movingStartFrame
+        ? resolveSnappedItemPosition(
+            {
+              id: getCanvasGenerationSelectionId(movingDialog.id),
+              x: movingPlaceholder.x,
+              y: movingPlaceholder.y,
+              width: movingPlaceholder.width,
+              height: movingPlaceholder.height,
+            },
+            proposedX,
+            proposedY,
+            getCanvasSnapItems({
+              layers,
+              generationDialogs,
+              excludedLayerIds: dragState.layerIds,
+              excludedGenerationDialogIds: targetDialogIds,
+            }),
+            dragState.startScale,
+          )
+        : { x: proposedX, y: proposedY, guide: null };
+  const appliedSnapOffset = {
+    x: snapped.x - proposedX,
+    y: snapped.y - proposedY,
+  };
+  return {
+    snapGuide: snapped.guide,
+    snapOffset: appliedSnapOffset,
+    generationDialogs: generationDialogs.map((dialog) => {
+    if (!targetDialogIds.includes(dialog.id) || !dialog.placeholder) {
+      return dialog;
+    }
+    const startFrame = startFrames.find((frame) => frame.id === dialog.id);
+    if (!startFrame) {
+      return dialog;
+    }
+    return {
+      ...dialog,
+      placeholder: {
+        ...dialog.placeholder,
+        x: startFrame.x + deltaX + appliedSnapOffset.x,
+        y: startFrame.y + deltaY + appliedSnapOffset.y,
+      },
+    };
+    }),
+  };
+}
+
+export function moveDragSelectedLayers({
+  dragState,
+  layers,
+  snapOffset = { x: 0, y: 0 },
+  pointer,
+}: {
+  dragState: Extract<DragState, { kind: 'generation-frame' }>;
+  layers: CanvasLayer[];
+  snapOffset?: CanvasPoint;
+  pointer: CanvasPoint;
+}) {
+  if (!dragState.layerIds.length) {
+    return layers;
+  }
+  const deltaX = (pointer.x - dragState.startClientX) / dragState.startScale;
+  const deltaY = (pointer.y - dragState.startClientY) / dragState.startScale;
+  return layers.map((layer) => {
+    if (!dragState.layerIds.includes(layer.id)) {
+      return layer;
+    }
+    const startLayer = dragState.startLayers.find((item) => item.id === layer.id);
+    if (!startLayer) {
+      return layer;
+    }
+    return {
+      ...layer,
+      x: startLayer.x + deltaX + snapOffset.x,
+      y: startLayer.y + deltaY + snapOffset.y,
+    };
+  });
+}
+
+export function createMinimapModel({
+  layers,
+  viewport,
+  canvasSize,
+}: {
+  layers: CanvasLayer[];
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+}): StageMinimapModel | null {
+  const layerBounds = getLayerBounds(layers);
+  if (!layerBounds) {
+    return null;
+  }
+
+  const visibleBounds = {
+    minX: (0 - viewport.x) / viewport.scale,
+    minY: (0 - viewport.y) / viewport.scale,
+    maxX: (canvasSize.width - viewport.x) / viewport.scale,
+    maxY: (canvasSize.height - viewport.y) / viewport.scale,
+  };
+  const bounds = {
+    minX: Math.min(layerBounds.minX, visibleBounds.minX),
+    minY: Math.min(layerBounds.minY, visibleBounds.minY),
+    maxX: Math.max(layerBounds.maxX, visibleBounds.maxX),
+    maxY: Math.max(layerBounds.maxY, visibleBounds.maxY),
+  };
+  const boundsWidth = Math.max(1, bounds.maxX - bounds.minX);
+  const boundsHeight = Math.max(1, bounds.maxY - bounds.minY);
+  const scale = Math.min(
+    (MINIMAP_SIZE.width - MINIMAP_PADDING * 2) / boundsWidth,
+    (MINIMAP_SIZE.height - MINIMAP_PADDING * 2) / boundsHeight,
+  );
+  const projectRect = (rect: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+  }) => ({
+    left: MINIMAP_PADDING + (rect.minX - bounds.minX) * scale,
+    top: MINIMAP_PADDING + (rect.minY - bounds.minY) * scale,
+    width: Math.max(2, (rect.maxX - rect.minX) * scale),
+    height: Math.max(2, (rect.maxY - rect.minY) * scale),
+  });
+
+  return {
+    bounds,
+    scale,
+    layers: layers.map((layer) => ({
+      id: layer.id,
+      title: layer.title,
+      rect: projectRect({
+        minX: layer.x,
+        minY: layer.y,
+        maxX: layer.x + layer.width,
+        maxY: layer.y + layer.height,
+      }),
+    })),
+    viewport: projectRect(visibleBounds),
+  };
+}
+
+export function moveViewportFromMinimapPointer({
+  viewport,
+  canvasSize,
+  minimapModel,
+  pointer,
+}: {
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+  minimapModel: StageMinimapModel;
+  pointer: CanvasPoint;
+}) {
+  const localX = clamp(pointer.x, 0, MINIMAP_SIZE.width);
+  const localY = clamp(pointer.y, 0, MINIMAP_SIZE.height);
+  const worldX =
+    minimapModel.bounds.minX +
+    (localX - MINIMAP_PADDING) / minimapModel.scale;
+  const worldY =
+    minimapModel.bounds.minY +
+    (localY - MINIMAP_PADDING) / minimapModel.scale;
+
+  return {
+    ...viewport,
+    x: canvasSize.width / 2 - worldX * viewport.scale,
+    y: canvasSize.height / 2 - worldY * viewport.scale,
+  };
+}
+
+export function moveViewportFromMinimapDrag(
+  dragState: Extract<DragState, { kind: 'minimap' }>,
+  pointer: CanvasPoint,
+) {
+  const deltaWorldX =
+    ((pointer.x - dragState.startClientX) / dragState.minimapScale) *
+    MINIMAP_DRAG_SENSITIVITY;
+  const deltaWorldY =
+    ((pointer.y - dragState.startClientY) / dragState.minimapScale) *
+    MINIMAP_DRAG_SENSITIVITY;
+
+  return {
+    ...dragState.startViewport,
+    x: dragState.startViewport.x - deltaWorldX * dragState.startViewport.scale,
+    y: dragState.startViewport.y - deltaWorldY * dragState.startViewport.scale,
+  };
+}
+
+export function getDefaultCanvasScreenCenter(canvasSize = DEFAULT_CANVAS_SIZE) {
+  return {
+    x: canvasSize.width / 2,
+    y: canvasSize.height / 2,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts b/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts
new file mode 100644
index 000000000..4cc91f02a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasLayerCommandModel.test.ts
@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createCanvasLayerClipboard,
+  duplicateCanvasLayers,
+  flipCanvasLayers,
+  getCanvasLayersByIds,
+  groupCanvasLayers,
+  moveCanvasLayers,
+  removeCanvasLayers,
+  resolveContextTargetLayerIds,
+  toggleCanvasLayersLock,
+  toggleCanvasLayersVisibility,
+  ungroupCanvasLayers,
+} from './ImageCanvasLayerCommandModel';
+import type {
+  CanvasContextMenuState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+
+function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 10,
+    y: 20,
+    width: 100,
+    height: 80,
+    originalWidth: 100,
+    originalHeight: 80,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasLayerCommandModel', () => {
+  it('resolves context menu targets from the current multi-selection', () => {
+    const menu: CanvasContextMenuState = {
+      kind: 'layer',
+      x: 0,
+      y: 0,
+      layerId: 'layer-b',
+      canvasPoint: { x: 10, y: 20 },
+    };
+
+    expect(resolveContextTargetLayerIds(menu, ['layer-a', 'layer-b'])).toEqual([
+      'layer-a',
+      'layer-b',
+    ]);
+    expect(resolveContextTargetLayerIds(menu, ['layer-a'])).toEqual(['layer-b']);
+    expect(
+      resolveContextTargetLayerIds(
+        { kind: 'blank', x: 0, y: 0, canvasPoint: { x: 0, y: 0 } },
+        ['layer-a'],
+      ),
+    ).toEqual([]);
+  });
+
+  it('duplicates layers to a canvas point while preserving relative offsets', () => {
+    const first = createLayer({ id: 'first', title: '第一张', x: 20, y: 30 });
+    const second = createLayer({
+      id: 'second',
+      title: '第二张',
+      x: 70,
+      y: 90,
+      zIndex: 4,
+      groupId: 'group-old',
+    });
+
+    const duplicated = duplicateCanvasLayers({
+      sourceLayers: [first, second],
+      allLayers: [first, second],
+      canvasPoint: { x: 300, y: 200 },
+      stamp: 'test',
+    });
+
+    expect(duplicated).toMatchObject([
+      {
+        id: 'layer-copy-test-0',
+        resourceId: 'local-resource-copy-test-0',
+        title: '第一张 副本',
+        x: 300,
+        y: 200,
+        zIndex: 5,
+        groupId: null,
+      },
+      {
+        id: 'layer-copy-test-1',
+        resourceId: 'local-resource-copy-test-1',
+        title: '第二张 副本',
+        x: 350,
+        y: 260,
+        zIndex: 6,
+        groupId: null,
+      },
+    ]);
+
+    const cutPaste = duplicateCanvasLayers({
+      sourceLayers: [first],
+      allLayers: [first, second],
+      renameCopies: false,
+      stamp: 'cut',
+    });
+    expect(cutPaste[0]?.title).toBe('第一张');
+    expect(cutPaste[0]?.x).toBe(first.x + 32);
+  });
+
+  it('creates a cloned clipboard and removes target layers', () => {
+    const layers = [
+      createLayer({ id: 'first' }),
+      createLayer({ id: 'second', generationInputs: { fields: [], references: [] } }),
+    ];
+
+    const clipboard = createCanvasLayerClipboard(layers, ['second'], 'copy');
+
+    expect(clipboard?.mode).toBe('copy');
+    expect(clipboard?.layers).toEqual([layers[1]]);
+    expect(clipboard?.layers[0]).not.toBe(layers[1]);
+    expect(getCanvasLayersByIds(layers, ['first'])).toEqual([layers[0]]);
+    expect(removeCanvasLayers(layers, ['first'])).toEqual([layers[1]]);
+  });
+
+  it('moves layer z-indexes with the same commands as the context menu', () => {
+    const layers = [
+      createLayer({ id: 'bottom', zIndex: 1 }),
+      createLayer({ id: 'middle', zIndex: 3 }),
+      createLayer({ id: 'top', zIndex: 8 }),
+    ];
+
+    expect(moveCanvasLayers(layers, ['middle'], 'up')[1]?.zIndex).toBe(4);
+    expect(moveCanvasLayers(layers, ['middle'], 'down')[1]?.zIndex).toBe(2);
+    expect(moveCanvasLayers(layers, ['bottom', 'middle'], 'top')).toMatchObject([
+      { id: 'bottom', zIndex: 9 },
+      { id: 'middle', zIndex: 10 },
+      { id: 'top', zIndex: 8 },
+    ]);
+    expect(
+      moveCanvasLayers(layers, ['bottom', 'middle'], 'bottom'),
+    ).toMatchObject([
+      { id: 'bottom', zIndex: -2 },
+      { id: 'middle', zIndex: -1 },
+      { id: 'top', zIndex: 8 },
+    ]);
+  });
+
+  it('groups, ungroups, toggles visibility and lock, and flips layers', () => {
+    const layers = [
+      createLayer({ id: 'first', hidden: true, locked: true }),
+      createLayer({ id: 'second' }),
+      createLayer({ id: 'third' }),
+    ];
+    const targetIds = ['first', 'second'];
+
+    const groupedLayers = groupCanvasLayers(layers, targetIds, 'group-next');
+    expect(groupedLayers[0]?.groupId).toBe('group-next');
+    expect(groupedLayers[1]?.groupId).toBe('group-next');
+    expect(groupedLayers[2]?.groupId).toBeUndefined();
+
+    const ungroupedLayers = ungroupCanvasLayers(groupedLayers, targetIds);
+    expect(ungroupedLayers[0]?.groupId).toBeNull();
+    expect(ungroupedLayers[1]?.groupId).toBeNull();
+    expect(ungroupedLayers[2]?.groupId).toBeUndefined();
+
+    const hiddenLayers = toggleCanvasLayersVisibility(layers, targetIds);
+    expect(hiddenLayers[0]?.hidden).toBe(true);
+    expect(hiddenLayers[1]?.hidden).toBe(true);
+    expect(hiddenLayers[2]?.hidden).toBeUndefined();
+
+    const shownLayers = toggleCanvasLayersVisibility([
+      createLayer({ id: 'first', hidden: true }),
+      createLayer({ id: 'second', hidden: true }),
+    ], targetIds);
+    expect(shownLayers[0]?.hidden).toBe(false);
+    expect(shownLayers[1]?.hidden).toBe(false);
+
+    const lockedLayers = toggleCanvasLayersLock(layers, targetIds);
+    expect(lockedLayers[0]?.locked).toBe(true);
+    expect(lockedLayers[1]?.locked).toBe(true);
+    expect(lockedLayers[2]?.locked).toBeUndefined();
+
+    const flippedXLayers = flipCanvasLayers(layers, targetIds, 'x');
+    expect(flippedXLayers[0]?.flipX).toBe(true);
+    expect(flippedXLayers[1]?.flipX).toBe(true);
+    expect(flippedXLayers[2]?.flipX).toBeUndefined();
+
+    const flippedYLayers = flipCanvasLayers(layers, targetIds, 'y');
+    expect(flippedYLayers[0]?.flipY).toBe(true);
+    expect(flippedYLayers[1]?.flipY).toBe(true);
+    expect(flippedYLayers[2]?.flipY).toBeUndefined();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasLayerCommandModel.ts b/src/components/image-editor/ImageCanvasLayerCommandModel.ts
new file mode 100644
index 000000000..d2dab1a76
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasLayerCommandModel.ts
@@ -0,0 +1,219 @@
+import type {
+  CanvasClipboard,
+  CanvasContextMenuState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+
+export type CanvasLayerMoveMode = 'up' | 'down' | 'top' | 'bottom';
+
+export type CanvasLayerFlipAxis = 'x' | 'y';
+
+type CanvasPoint = {
+  x: number;
+  y: number;
+};
+
+function cloneLayer(layer: CanvasLayer): CanvasLayer {
+  return {
+    ...layer,
+    generationInputs: layer.generationInputs
+      ? {
+          fields: layer.generationInputs.fields.map((field) => ({ ...field })),
+          references: layer.generationInputs.references.map((reference) => ({
+            ...reference,
+          })),
+        }
+      : layer.generationInputs,
+  };
+}
+
+export function resolveContextTargetLayerIds(
+  menu: CanvasContextMenuState | null,
+  selectedLayerIds: string[],
+) {
+  if (menu?.kind !== 'layer') {
+    return [];
+  }
+  return selectedLayerIds.includes(menu.layerId)
+    ? [...selectedLayerIds]
+    : [menu.layerId];
+}
+
+export function getCanvasLayersByIds(
+  layers: CanvasLayer[],
+  targetIds: string[],
+) {
+  return layers.filter((layer) => targetIds.includes(layer.id));
+}
+
+export function duplicateCanvasLayers({
+  sourceLayers,
+  allLayers,
+  canvasPoint,
+  renameCopies = true,
+  stamp = Date.now(),
+}: {
+  sourceLayers: CanvasLayer[];
+  allLayers: CanvasLayer[];
+  canvasPoint?: CanvasPoint;
+  renameCopies?: boolean;
+  stamp?: number | string;
+}) {
+  if (!sourceLayers.length) {
+    return [];
+  }
+
+  const minX = Math.min(...sourceLayers.map((layer) => layer.x));
+  const minY = Math.min(...sourceLayers.map((layer) => layer.y));
+  const maxZIndex = allLayers.reduce(
+    (maxZ, layer) => Math.max(maxZ, layer.zIndex),
+    0,
+  );
+
+  return sourceLayers.map((layer, index) => ({
+    ...cloneLayer(layer),
+    id: `layer-copy-${stamp}-${index}`,
+    resourceId: `local-resource-copy-${stamp}-${index}`,
+    title: renameCopies ? `${layer.title} 副本` : layer.title,
+    x: canvasPoint ? canvasPoint.x + (layer.x - minX) : layer.x + 32,
+    y: canvasPoint ? canvasPoint.y + (layer.y - minY) : layer.y + 32,
+    zIndex: maxZIndex + index + 1,
+    groupId: null,
+  }));
+}
+
+export function createCanvasLayerClipboard(
+  layers: CanvasLayer[],
+  targetIds: string[],
+  mode: CanvasClipboard['mode'],
+): CanvasClipboard | null {
+  const targetLayers = getCanvasLayersByIds(layers, targetIds);
+  if (!targetLayers.length) {
+    return null;
+  }
+  return {
+    layers: targetLayers.map(cloneLayer),
+    mode,
+  };
+}
+
+export function removeCanvasLayers(layers: CanvasLayer[], targetIds: string[]) {
+  if (!targetIds.length) {
+    return layers;
+  }
+  return layers.filter((layer) => !targetIds.includes(layer.id));
+}
+
+export function updateCanvasLayersByIds(
+  layers: CanvasLayer[],
+  targetIds: string[],
+  updater: (layer: CanvasLayer, targetIds: string[]) => CanvasLayer,
+) {
+  if (!targetIds.length) {
+    return layers;
+  }
+  return layers.map((layer) =>
+    targetIds.includes(layer.id) ? updater(layer, targetIds) : layer,
+  );
+}
+
+export function moveCanvasLayers(
+  layers: CanvasLayer[],
+  targetIds: string[],
+  mode: CanvasLayerMoveMode,
+) {
+  if (!targetIds.length) {
+    return layers;
+  }
+  const maxZIndex = layers.reduce(
+    (maxZ, layer) => Math.max(maxZ, layer.zIndex),
+    0,
+  );
+  const minZIndex = layers.reduce(
+    (minZ, layer) => Math.min(minZ, layer.zIndex),
+    0,
+  );
+  let offsetIndex = 0;
+
+  return updateCanvasLayersByIds(layers, targetIds, (layer) => {
+    if (mode === 'up') {
+      return { ...layer, zIndex: layer.zIndex + 1 };
+    }
+    if (mode === 'down') {
+      return { ...layer, zIndex: layer.zIndex - 1 };
+    }
+    offsetIndex += 1;
+    if (mode === 'top') {
+      return { ...layer, zIndex: maxZIndex + offsetIndex };
+    }
+    return {
+      ...layer,
+      zIndex: minZIndex - (targetIds.length - offsetIndex + 1),
+    };
+  });
+}
+
+export function groupCanvasLayers(
+  layers: CanvasLayer[],
+  targetIds: string[],
+  groupId: string,
+) {
+  return updateCanvasLayersByIds(layers, targetIds, (layer) => ({
+    ...layer,
+    groupId,
+  }));
+}
+
+export function ungroupCanvasLayers(
+  layers: CanvasLayer[],
+  targetIds: string[],
+) {
+  return updateCanvasLayersByIds(layers, targetIds, (layer) => ({
+    ...layer,
+    groupId: null,
+  }));
+}
+
+export function toggleCanvasLayersVisibility(
+  layers: CanvasLayer[],
+  targetIds: string[],
+) {
+  const shouldHide = getCanvasLayersByIds(layers, targetIds).some(
+    (layer) => !layer.hidden,
+  );
+  return updateCanvasLayersByIds(layers, targetIds, (layer) => ({
+    ...layer,
+    hidden: shouldHide,
+  }));
+}
+
+export function toggleCanvasLayersLock(
+  layers: CanvasLayer[],
+  targetIds: string[],
+) {
+  const shouldLock = getCanvasLayersByIds(layers, targetIds).some(
+    (layer) => !layer.locked,
+  );
+  return updateCanvasLayersByIds(layers, targetIds, (layer) => ({
+    ...layer,
+    locked: shouldLock,
+  }));
+}
+
+export function flipCanvasLayers(
+  layers: CanvasLayer[],
+  targetIds: string[],
+  axis: CanvasLayerFlipAxis,
+) {
+  return updateCanvasLayersByIds(layers, targetIds, (layer) =>
+    axis === 'x'
+      ? {
+          ...layer,
+          flipX: !layer.flipX,
+        }
+      : {
+          ...layer,
+          flipY: !layer.flipY,
+        },
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasLayerPanelView.tsx b/src/components/image-editor/ImageCanvasLayerPanelView.tsx
new file mode 100644
index 000000000..e19e2599a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasLayerPanelView.tsx
@@ -0,0 +1,90 @@
+import type { Dispatch, SetStateAction } from 'react';
+
+import { SidebarMediaItem } from './ImageCanvasEditorPrimitives';
+import type {
+  CanvasContextMenuState,
+  CanvasLayer,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+
+export type ImageCanvasLayerPanelViewProps = {
+  layers: CanvasLayer[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  setImageContextMenu: Dispatch<SetStateAction<ImageContextMenuState | null>>;
+  setContextMenu: Dispatch<SetStateAction<CanvasContextMenuState | null>>;
+  selectSingleLayer: (layerId: string | null) => void;
+  resolveContextMenuPosition: (
+    clientX: number,
+    clientY: number,
+    menuKind: 'blank' | 'layer',
+  ) => Omit<CanvasContextMenuState, 'kind' | 'layerId' | 'canvasPoint'>;
+  getCanvasPointFromClient: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number };
+};
+
+export function ImageCanvasLayerPanelView({
+  layers,
+  selectedLayerId,
+  selectedLayerIds,
+  setImageContextMenu,
+  setContextMenu,
+  selectSingleLayer,
+  resolveContextMenuPosition,
+  getCanvasPointFromClient,
+}: ImageCanvasLayerPanelViewProps) {
+  return (
+    <div className="image-canvas-editor__layers-list">
+      {layers
+        .slice()
+        .sort((left, right) => right.zIndex - left.zIndex)
+        .map((layer) => (
+          <SidebarMediaItem
+            key={layer.id}
+            title={layer.title}
+            detail={[
+              `${Math.round(layer.width)} x ${Math.round(layer.height)}`,
+              layer.groupId ? '已打组' : null,
+              layer.hidden ? '已隐藏' : null,
+              layer.locked ? '已锁定' : null,
+            ]
+              .filter(Boolean)
+              .join(' · ')}
+            imageSrc={layer.src}
+            imageAlt={`图层缩略图：${layer.title}`}
+            selected={selectedLayerId === layer.id}
+            primaryLabel={`选择图层${layer.title}`}
+            onPrimaryClick={() => selectSingleLayer(layer.id)}
+            rowClassName="image-canvas-editor__layer-row"
+            primaryClassName="image-canvas-editor__layer-row-button"
+            thumbnailClassName="image-canvas-editor__layer-row-thumb"
+            metaClassName="image-canvas-editor__layer-row-meta"
+            onContextMenu={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+              if (!selectedLayerIds.includes(layer.id)) {
+                selectSingleLayer(layer.id);
+              }
+              const position = resolveContextMenuPosition(
+                event.clientX,
+                event.clientY,
+                'layer',
+              );
+              setImageContextMenu(null);
+              setContextMenu({
+                kind: 'layer',
+                layerId: layer.id,
+                ...position,
+                canvasPoint: getCanvasPointFromClient(
+                  event.clientX,
+                  event.clientY,
+                ),
+              });
+            }}
+          />
+        ))}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasMediaModel.ts b/src/components/image-editor/ImageCanvasMediaModel.ts
new file mode 100644
index 000000000..3eab66708
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasMediaModel.ts
@@ -0,0 +1,80 @@
+export function normalizeCanvasDurationSeconds(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : null;
+}
+
+export function formatCanvasDurationLabel(value: unknown) {
+  const durationSeconds = normalizeCanvasDurationSeconds(value);
+  if (durationSeconds === null) {
+    return '--:--';
+  }
+
+  const totalSeconds = Math.max(1, Math.round(durationSeconds));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  const paddedSeconds = String(seconds).padStart(2, '0');
+
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, '0')}:${paddedSeconds}`;
+  }
+
+  return `${minutes}:${paddedSeconds}`;
+}
+
+export function formatCanvasDurationMetric(value: unknown) {
+  // 中文注释：音频对象没有视觉分辨率语义，画布角标统一显示时长。
+  return `时长 ${formatCanvasDurationLabel(value)}`;
+}
+
+type MediaPreviewTone = 'audio' | 'video';
+
+type MediaPreviewMarker = {
+  tone: MediaPreviewTone;
+  variant: number;
+};
+
+const MEDIA_PREVIEW_VARIANT_COUNT = 6;
+
+function hashMediaPreviewSeed(seed: string) {
+  let hash = 0;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash = (hash * 31 + seed.charCodeAt(index)) >>> 0;
+  }
+  return hash;
+}
+
+export function getCanvasMediaPreviewMarker({
+  mediaType,
+  assetKind,
+  title,
+  src,
+}: {
+  mediaType?: string | null;
+  assetKind?: string | null;
+  title?: string | null;
+  src?: string | null;
+}): MediaPreviewMarker | null {
+  if (mediaType !== 'audio' && mediaType !== 'video') {
+    return null;
+  }
+  const seed = `${assetKind ?? ''}|${title ?? ''}|${src ?? ''}`;
+  return {
+    tone: mediaType,
+    variant: hashMediaPreviewSeed(seed) % MEDIA_PREVIEW_VARIANT_COUNT,
+  };
+}
+
+export function getCanvasMediaPreviewClassName(
+  marker: MediaPreviewMarker | null,
+) {
+  if (!marker) {
+    return '';
+  }
+  return [
+    'image-canvas-editor__media-preview',
+    `image-canvas-editor__media-preview--${marker.tone}`,
+    `image-canvas-editor__media-preview--variant-${marker.variant}`,
+  ].join(' ');
+}
diff --git a/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx b/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx
new file mode 100644
index 000000000..cdabe319f
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasMetadataModalView.test.tsx
@@ -0,0 +1,193 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { ImageCanvasMetadataModalView } from './ImageCanvasMetadataModalView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '生成主图',
+    src: 'data:image/png;base64,layer',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    originalWidth: 1024,
+    originalHeight: 768,
+    zIndex: 1,
+    sourceType: 'generated',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasMetadataModalView', () => {
+  it('renders generated layer metadata with generation inputs and references', () => {
+    render(
+      <ImageCanvasMetadataModalView
+        layer={createLayer({
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'gpt-image-2-task-123',
+          objectKey: 'generated/object.png',
+          generationInputs: {
+            fields: [{ title: '生成提示词', value: '清爽游戏按钮' }],
+            references: [
+              {
+                title: '参考图',
+                label: '角色立绘',
+                refType: 'project-resource',
+                refId: 'resource-reference',
+              },
+            ],
+          },
+        })}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '图片信息' });
+
+    expect(within(dialog).queryByText('生成主图')).toBeNull();
+    expect(within(dialog).getByText('生成图片')).toBeTruthy();
+    expect(within(dialog).getByText('生成提示词')).toBeTruthy();
+    expect(within(dialog).getByText('清爽游戏按钮')).toBeTruthy();
+    expect(within(dialog).getByText('参考图')).toBeTruthy();
+    expect(within(dialog).getByText('角色立绘')).toBeTruthy();
+    expect(within(dialog).getByText('项目资源 · resource-reference')).toBeTruthy();
+    expect(within(dialog).getByText('gpt-image-2')).toBeTruthy();
+    expect(within(dialog).getByText('1024 x 768 px')).toBeTruthy();
+    expect(within(dialog).queryByText('Provider')).toBeNull();
+    expect(within(dialog).queryByText(/VectorEngine/u)).toBeNull();
+    expect(within(dialog).queryByText(/task-/u)).toBeNull();
+    expect(within(dialog).getByText('123')).toBeTruthy();
+    expect(within(dialog).getByText('generated/object.png')).toBeTruthy();
+  });
+
+  it('renders nanobanana2 instead of the raw Gemini image model id', () => {
+    render(
+      <ImageCanvasMetadataModalView
+        layer={createLayer({
+          model: 'gemini-3.1-flash-image-preview',
+        })}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '图片信息' });
+
+    expect(within(dialog).getByText('nanobanana2')).toBeTruthy();
+    expect(
+      within(dialog).queryByText('gemini-3.1-flash-image-preview'),
+    ).toBeNull();
+  });
+
+  it('renders upload fallback values and closes through the modal shell', () => {
+    const onClose = vi.fn();
+    render(
+      <ImageCanvasMetadataModalView
+        layer={createLayer({
+          title: '上传素材',
+          sourceType: 'uploaded',
+          model: null,
+          provider: null,
+          taskId: null,
+          objectKey: null,
+          assetObjectId: 'asset-object-1',
+          generationInputs: null,
+        })}
+        onClose={onClose}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '图片信息' });
+
+    expect(within(dialog).queryByText('上传素材')).toBeNull();
+    expect(within(dialog).getByText('上传图片')).toBeTruthy();
+    expect(within(dialog).getAllByText('-').length).toBeGreaterThanOrEqual(3);
+    expect(within(dialog).getByText('asset-object-1')).toBeTruthy();
+
+    fireEvent.click(within(dialog).getByRole('button', { name: '关闭图片信息' }));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders generated video metadata with video labels and close action', () => {
+    const onClose = vi.fn();
+    render(
+      <ImageCanvasMetadataModalView
+        layer={createLayer({
+          title: '生成视频 1',
+          src: '/generated-editor-videos/video-task-1/preview.mp4',
+          mediaType: 'video',
+          assetKind: 'video',
+          originalWidth: 1280,
+          originalHeight: 720,
+          model: 'kling3.0-omni',
+          taskId: 'video-task-1',
+          generationInputs: {
+            fields: [{ title: '视频描述', value: '让角色向镜头挥手' }],
+            references: [],
+          },
+        })}
+        onClose={onClose}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '视频信息' });
+
+    expect(within(dialog).getByText('视频类型')).toBeTruthy();
+    expect(within(dialog).getByText('生成视频')).toBeTruthy();
+    expect(within(dialog).getByText('视频描述')).toBeTruthy();
+    expect(within(dialog).getByText('让角色向镜头挥手')).toBeTruthy();
+    expect(within(dialog).getByText('kling3.0-omni')).toBeTruthy();
+    expect(within(dialog).getByText('1280 x 720 px')).toBeTruthy();
+
+    fireEvent.click(within(dialog).getByRole('button', { name: '关闭视频信息' }));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders generated audio metadata with duration instead of resolution', () => {
+    render(
+      <ImageCanvasMetadataModalView
+        layer={createLayer({
+          title: '游戏背景音乐',
+          src: '/generated-character-drafts/editor-audios/music.wav',
+          mediaType: 'audio',
+          assetKind: 'background-music',
+          originalWidth: 420,
+          originalHeight: 120,
+          model: 'suno',
+          taskId: 'audio-task-75',
+          durationSeconds: 75,
+          generationInputs: {
+            fields: [{ title: '音乐描述', value: '紧张的地下城循环音乐' }],
+            references: [],
+          },
+        })}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '音频信息' });
+
+    expect(within(dialog).getByText('音频类型')).toBeTruthy();
+    expect(within(dialog).getByText('游戏背景音乐')).toBeTruthy();
+    expect(within(dialog).getByText('音乐描述')).toBeTruthy();
+    expect(within(dialog).getByText('紧张的地下城循环音乐')).toBeTruthy();
+    expect(within(dialog).getByText('时长')).toBeTruthy();
+    expect(within(dialog).getByText('1:15')).toBeTruthy();
+    expect(within(dialog).queryByText('Resolution')).toBeNull();
+    expect(within(dialog).queryByText('420 x 120 px')).toBeNull();
+  });
+
+  it('does not render a dialog when no layer is selected', () => {
+    render(<ImageCanvasMetadataModalView layer={null} onClose={vi.fn()} />);
+
+    expect(screen.queryByRole('dialog', { name: '图片信息' })).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasMetadataModalView.tsx b/src/components/image-editor/ImageCanvasMetadataModalView.tsx
new file mode 100644
index 000000000..093a23a7c
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasMetadataModalView.tsx
@@ -0,0 +1,117 @@
+import { UnifiedModal } from '../common/UnifiedModal';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import {
+  formatLayerImageType,
+  getEditorImageModelDisplayName,
+} from './ImageCanvasGenerationModel';
+import { formatCanvasDurationMetric } from './ImageCanvasMediaModel';
+
+export type ImageCanvasMetadataModalViewProps = {
+  layer: CanvasLayer | null;
+  onClose: () => void;
+};
+
+function formatTaskIdForDisplay(taskId?: string | null) {
+  const numericParts = taskId?.match(/\d+/gu);
+  return numericParts?.length ? numericParts[numericParts.length - 1] : '-';
+}
+
+function formatReferenceType(refType: 'project-resource' | 'asset') {
+  return refType === 'project-resource' ? '项目资源' : '素材';
+}
+
+export function ImageCanvasMetadataModalView({
+  layer,
+  onClose,
+}: ImageCanvasMetadataModalViewProps) {
+  const mediaLabel =
+    layer?.mediaType === 'audio'
+      ? '音频'
+      : layer?.mediaType === 'video'
+        ? '视频'
+        : '图片';
+  return (
+    <UnifiedModal
+      open={Boolean(layer)}
+      title={`${mediaLabel}信息`}
+      size="sm"
+      closeLabel={`关闭${mediaLabel}信息`}
+      onClose={onClose}
+      panelClassName="image-canvas-editor__metadata-dialog"
+      bodyClassName="image-canvas-editor__metadata-body"
+    >
+      {layer ? (
+        <dl className="image-canvas-editor__metadata-grid">
+          <dt>{mediaLabel}类型</dt>
+          <dd>{formatLayerImageType(layer)}</dd>
+          <dt>生成输入</dt>
+          <dd className="image-canvas-editor__metadata-inputs">
+            {layer.generationInputs?.fields.length ||
+            layer.generationInputs?.references.length ? (
+              <>
+                {layer.generationInputs.fields.map((field) => (
+                  <div
+                    key={`${field.title}-${field.value}`}
+                    className="image-canvas-editor__metadata-input-field"
+                  >
+                    <span className="image-canvas-editor__metadata-input-title">
+                      {field.title}
+                    </span>
+                    <span>{field.value}</span>
+                  </div>
+                ))}
+                {layer.generationInputs.references.length ? (
+                  <div className="image-canvas-editor__metadata-reference-list">
+                    {layer.generationInputs.references.map((reference) => (
+                      <div
+                        key={`${reference.title}-${reference.label}-${reference.refType}-${reference.refId}`}
+                        className="image-canvas-editor__metadata-reference-card"
+                      >
+                        <span className="image-canvas-editor__metadata-reference-copy">
+                          <span className="image-canvas-editor__metadata-input-title">
+                            {reference.title}
+                          </span>
+                          <span>{reference.label}</span>
+                          <span className="image-canvas-editor__metadata-reference-id">
+                            {formatReferenceType(reference.refType)} ·{' '}
+                            {reference.refId}
+                          </span>
+                        </span>
+                      </div>
+                    ))}
+                  </div>
+                ) : null}
+              </>
+            ) : (
+              '-'
+            )}
+          </dd>
+          <dt>Model</dt>
+          <dd>{layer.model ? getEditorImageModelDisplayName(layer.model) : '-'}</dd>
+          {layer.mediaType === 'audio' ? (
+            <>
+              <dt>时长</dt>
+              <dd>
+                {formatCanvasDurationMetric(layer.durationSeconds).replace(
+                  /^时长\s*/u,
+                  '',
+                )}
+              </dd>
+            </>
+          ) : (
+            <>
+              <dt>Resolution</dt>
+              <dd>
+                {layer.originalWidth} x {layer.originalHeight} px
+              </dd>
+            </>
+          )}
+          <dt>Task</dt>
+          <dd>{formatTaskIdForDisplay(layer.taskId)}</dd>
+          <dt>Object</dt>
+          <dd>{layer.objectKey ?? layer.assetObjectId ?? '-'}</dd>
+        </dl>
+      ) : null}
+    </UnifiedModal>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasOverlayModel.test.ts b/src/components/image-editor/ImageCanvasOverlayModel.test.ts
new file mode 100644
index 000000000..d3a5955c1
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasOverlayModel.test.ts
@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CharacterAnimationPanelState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import {
+  isCanvasGenerationComposerVisible,
+  resolveCharacterAnimationPanelStyle,
+  resolveGenerationAnchor,
+  resolveGenerationComposerStyle,
+  resolveIconComposerStyle,
+  resolveQuickEditPanelStyle,
+  resolveSelectedToolbarStyle,
+} from './ImageCanvasOverlayModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-a',
+    resourceId: 'resource-a',
+    title: '图层A',
+    src: 'data:image/png;base64,layer',
+    x: 100,
+    y: 80,
+    width: 240,
+    height: 120,
+    originalWidth: 240,
+    originalHeight: 120,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createDialog(
+  overrides: Partial<CanvasGenerationDialogState> = {},
+): CanvasGenerationDialogState {
+  return {
+    id: 'dialog-a',
+    mode: 'generate',
+    prompt: '',
+    status: 'idle',
+    placeholder: {
+      x: 300,
+      y: 200,
+      width: 360,
+      height: 260,
+      originalWidth: 1024,
+      originalHeight: 1024,
+    },
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasOverlayModel', () => {
+  it('anchors generation composer to generated layers before placeholders', () => {
+    const generatedLayer = createLayer({ x: 40, y: 60, width: 320, height: 180 });
+    const dialog = createDialog({ generatedLayerId: generatedLayer.id });
+    const anchor = resolveGenerationAnchor({ dialog, generatedLayer });
+
+    expect(anchor).toBe(generatedLayer);
+    expect(
+      resolveGenerationComposerStyle({
+        dialog,
+        anchor,
+        viewport: { x: 10, y: 20, scale: 2 },
+      }),
+    ).toEqual({
+      left: 410,
+      top: 510,
+    });
+  });
+
+  it('hides generation composer while generating or explicitly closed', () => {
+    const placeholder = createDialog().placeholder ?? null;
+
+    expect(
+      resolveGenerationComposerStyle({
+        dialog: createDialog({ status: 'generating' }),
+        anchor: placeholder,
+        viewport: { x: 0, y: 0, scale: 1 },
+      }),
+    ).toBeNull();
+    expect(
+      resolveGenerationComposerStyle({
+        dialog: createDialog({ composerOpen: false }),
+        anchor: placeholder,
+        viewport: { x: 0, y: 0, scale: 1 },
+      }),
+    ).toBeNull();
+  });
+
+  it('keeps icon composer aligned to the base generation composer width', () => {
+    expect(
+      resolveIconComposerStyle({
+        dialog: createDialog({ mode: 'icon' }),
+        composerStyle: { left: 100, top: 200 },
+      }),
+    ).toEqual({
+      left: 100,
+      top: 200,
+    });
+
+    expect(
+      resolveIconComposerStyle({
+        dialog: createDialog({ mode: 'generate' }),
+        composerStyle: { left: 100, top: 200 },
+      }),
+    ).toBeNull();
+  });
+
+  it('keeps selected layer toolbar inside the canvas width', () => {
+    expect(
+      resolveSelectedToolbarStyle({
+        selectedLayer: createLayer({ x: -500, y: -100 }),
+        viewport: { x: 0, y: 0, scale: 1 },
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ left: 132, top: 10 });
+
+    expect(
+      resolveSelectedToolbarStyle({
+        selectedLayer: createLayer({ x: 1200, y: 100 }),
+        viewport: { x: 0, y: 0, scale: 1 },
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ left: 768, top: 88 });
+  });
+
+  it('positions quick edit and character animation panels with viewport bounds', () => {
+    const sourceLayer = createLayer({ x: 740, y: 460, width: 240, height: 180 });
+    const quickEditPanel: QuickEditPanelState = {
+      sourceLayerId: sourceLayer.id,
+      prompt: '',
+      size: '1024x1024',
+      model: 'gpt-image-2',
+      status: 'idle',
+    };
+    const characterPanel: CharacterAnimationPanelState = {
+      sourceLayerId: sourceLayer.id,
+      promptText: '',
+      resolution: '480p',
+      ratio: 'same',
+      frameCount: 32,
+      durationSeconds: 4,
+      status: 'idle',
+    };
+
+    expect(
+      resolveQuickEditPanelStyle({
+        panel: quickEditPanel,
+        sourceLayer,
+        viewport: { x: 20, y: 10, scale: 1 },
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ left: 880, top: 280 });
+    expect(
+      resolveCharacterAnimationPanelStyle({
+        panel: characterPanel,
+        sourceLayer,
+        viewport: { x: 20, y: 10, scale: 1 },
+        canvasSize: { width: 900, height: 640 },
+      }),
+    ).toEqual({ left: 536, top: 120 });
+  });
+
+  it('recognizes canvas generation composer dialog modes', () => {
+    expect(isCanvasGenerationComposerVisible(createDialog({ mode: 'generate' }))).toBe(
+      true,
+    );
+    expect(isCanvasGenerationComposerVisible(createDialog({ mode: 'spec' }))).toBe(
+      true,
+    );
+    expect(
+      isCanvasGenerationComposerVisible(createDialog({ mode: 'publication' })),
+    ).toBe(true);
+    expect(
+      isCanvasGenerationComposerVisible({
+        mode: 'edit',
+        prompt: '',
+        status: 'idle',
+      }),
+    ).toBe(false);
+    expect(isCanvasGenerationComposerVisible(null)).toBe(false);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasOverlayModel.ts b/src/components/image-editor/ImageCanvasOverlayModel.ts
new file mode 100644
index 000000000..92c58c541
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasOverlayModel.ts
@@ -0,0 +1,212 @@
+import {
+  clamp,
+  TOOLBAR_HALF_WIDTH,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogMode,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  CharacterAnimationPanelState,
+  CropExpandPanelState,
+  GenerateDialogState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+
+type CanvasSize = {
+  width: number;
+  height: number;
+};
+
+type OverlayAnchor = Pick<CanvasLayer, 'x' | 'y' | 'width' | 'height'>;
+
+export type CanvasOverlayStyle = {
+  left: number;
+  top: number;
+};
+
+export type CanvasComposerOverlayStyle = CanvasOverlayStyle & {
+  width?: string;
+};
+
+export function resolveGenerationAnchor({
+  dialog,
+  generatedLayer,
+}: {
+  dialog: CanvasGenerationDialogState | null;
+  generatedLayer: CanvasLayer | null;
+}) {
+  if (!dialog) {
+    return null;
+  }
+  return generatedLayer ?? dialog.placeholder ?? null;
+}
+
+export function resolveGenerationComposerStyle({
+  dialog,
+  anchor,
+  viewport,
+}: {
+  dialog: CanvasGenerationDialogState | null;
+  anchor: OverlayAnchor | null;
+  viewport: CanvasViewport;
+}): CanvasOverlayStyle | null {
+  if (
+    !dialog ||
+    dialog.status === 'generating' ||
+    dialog.composerOpen === false ||
+    !anchor
+  ) {
+    return null;
+  }
+  return {
+    left: viewport.x + (anchor.x + anchor.width / 2) * viewport.scale,
+    top: viewport.y + (anchor.y + anchor.height) * viewport.scale + 10,
+  };
+}
+
+export function resolveIconComposerStyle({
+  dialog,
+  composerStyle,
+}: {
+  dialog: CanvasGenerationDialogState | null;
+  composerStyle: CanvasOverlayStyle | null;
+}): CanvasComposerOverlayStyle | null {
+  if (dialog?.mode !== 'icon' || !composerStyle) {
+    return null;
+  }
+  return composerStyle;
+}
+
+export function resolveSelectedToolbarStyle({
+  selectedLayer,
+  viewport,
+  canvasSize,
+}: {
+  selectedLayer: CanvasLayer | null;
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+}): CanvasOverlayStyle | null {
+  if (!selectedLayer) {
+    return null;
+  }
+  return {
+    left: clamp(
+      viewport.x +
+        selectedLayer.x * viewport.scale +
+        (selectedLayer.width * viewport.scale) / 2,
+      TOOLBAR_HALF_WIDTH,
+      Math.max(TOOLBAR_HALF_WIDTH, canvasSize.width - TOOLBAR_HALF_WIDTH),
+    ),
+    top: Math.max(10, viewport.y + selectedLayer.y * viewport.scale - 12),
+  };
+}
+
+export function resolveQuickEditPanelStyle({
+  panel,
+  sourceLayer,
+  viewport,
+  canvasSize,
+}: {
+  panel: QuickEditPanelState | null;
+  sourceLayer: CanvasLayer | null;
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+}): CanvasOverlayStyle | null {
+  if (!panel || !sourceLayer) {
+    return null;
+  }
+  return {
+    left: clamp(
+      viewport.x +
+        (sourceLayer.x + sourceLayer.width / 2) * viewport.scale,
+      12,
+      Math.max(12, canvasSize.width - 12),
+    ),
+    top: clamp(
+      viewport.y +
+        (sourceLayer.y + sourceLayer.height) * viewport.scale +
+        12,
+      12,
+      Math.max(12, canvasSize.height - 360),
+    ),
+  };
+}
+
+export function resolveCropExpandPanelStyle({
+  panel,
+  sourceLayer,
+  viewport,
+  canvasSize,
+}: {
+  panel: CropExpandPanelState | null;
+  sourceLayer: CanvasLayer | null;
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+}): CanvasOverlayStyle | null {
+  if (!panel || !sourceLayer) {
+    return null;
+  }
+  return {
+    left: clamp(
+      viewport.x +
+        (sourceLayer.x + sourceLayer.width) * viewport.scale +
+        12,
+      12,
+      Math.max(12, canvasSize.width - 312),
+    ),
+    top: clamp(
+      viewport.y + sourceLayer.y * viewport.scale,
+      12,
+      Math.max(12, canvasSize.height - 320),
+    ),
+  };
+}
+
+export function resolveCharacterAnimationPanelStyle({
+  panel,
+  sourceLayer,
+  viewport,
+  canvasSize,
+}: {
+  panel: CharacterAnimationPanelState | null;
+  sourceLayer: CanvasLayer | null;
+  viewport: CanvasViewport;
+  canvasSize: CanvasSize;
+}): CanvasOverlayStyle | null {
+  if (!panel || !sourceLayer) {
+    return null;
+  }
+  return {
+    left: clamp(
+      viewport.x +
+        (sourceLayer.x + sourceLayer.width) * viewport.scale +
+        12,
+      12,
+      Math.max(12, canvasSize.width - 364),
+    ),
+    top: clamp(
+      viewport.y + sourceLayer.y * viewport.scale,
+      12,
+      Math.max(12, canvasSize.height - 520),
+    ),
+  };
+}
+
+export function isCanvasGenerationComposerVisible(
+  dialog: GenerateDialogState | null,
+): dialog is GenerateDialogState & { mode: CanvasGenerationDialogMode } {
+  return (
+    dialog?.mode === 'generate' ||
+    dialog?.mode === 'spec' ||
+    dialog?.mode === 'character' ||
+    dialog?.mode === 'icon' ||
+    dialog?.mode === 'ui-design' ||
+    dialog?.mode === 'quick-edit' ||
+    dialog?.mode === 'publication' ||
+    dialog?.mode === 'character-animation' ||
+    dialog?.mode === 'video' ||
+    dialog?.mode === 'audio-sound-effect' ||
+    dialog?.mode === 'audio-background-music'
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.test.tsx b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
new file mode 100644
index 000000000..f3dc3c4fa
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasPanelDockView.test.tsx
@@ -0,0 +1,112 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { StageMinimapModel } from './ImageCanvasInteractionModel';
+import { ImageCanvasPanelDockView } from './ImageCanvasPanelDockView';
+
+function renderPanelDock(
+  overrides: Partial<Parameters<typeof ImageCanvasPanelDockView>[0]> = {},
+) {
+  const props: Parameters<typeof ImageCanvasPanelDockView>[0] = {
+    viewport: { x: 0, y: 0, scale: 1 },
+    canvasBackgroundColor: '#f8fafc',
+    canvasBackgroundHexValue: '#f8fafc',
+    canUndo: true,
+    canRedo: false,
+    isZoomMenuOpen: false,
+    isBackgroundSettingsOpen: false,
+    activeSidebarPanel: null,
+    isMinimapOpen: false,
+    minimapModel: null,
+    onFitLayers: vi.fn(),
+    onUndoCanvasChange: vi.fn(),
+    onRedoCanvasChange: vi.fn(),
+    onUpdateScaleFromCenter: vi.fn(),
+    onToggleZoomMenu: vi.fn(),
+    onCloseZoomMenu: vi.fn(),
+    onToggleBackgroundSettings: vi.fn(),
+    onApplyCanvasBackgroundColor: vi.fn(),
+    onCanvasBackgroundHexChange: vi.fn(),
+    onToggleSidebarPanel: vi.fn(),
+    onToggleMinimap: vi.fn(),
+    onMinimapPointerDown: vi.fn(),
+    ...overrides,
+  };
+
+  render(<ImageCanvasPanelDockView {...props} />);
+
+  return props;
+}
+
+describe('ImageCanvasPanelDockView', () => {
+  it('renders panel dock actions and forwards common controls', () => {
+    const props = renderPanelDock({
+      activeSidebarPanel: 'assets',
+      isMinimapOpen: true,
+      minimapModel: {
+        bounds: { minX: 0, minY: 0, maxX: 100, maxY: 100 },
+        scale: 1,
+        layers: [],
+        viewport: { left: '10%', top: '12%', width: '20%', height: '24%' },
+      } satisfies StageMinimapModel,
+    });
+
+    const toolbar = screen.getByRole('toolbar', { name: '画布面板入口' });
+
+    expect(
+      within(toolbar).getByRole('button', { name: '打开素材' }).getAttribute(
+        'aria-pressed',
+      ),
+    ).toBe('true');
+    expect(
+      (
+        within(toolbar).getByRole('button', { name: '重做' }) as HTMLButtonElement
+      ).disabled,
+    ).toBe(true);
+    expect(screen.getByRole('button', { name: '画布小地图' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '重置画布视图' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '撤销' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '打开图层' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '切换小地图' }));
+
+    expect(props.onFitLayers).toHaveBeenCalledTimes(1);
+    expect(props.onUndoCanvasChange).toHaveBeenCalledTimes(1);
+    expect(props.onToggleSidebarPanel).toHaveBeenCalledWith('layers');
+    expect(props.onToggleMinimap).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders zoom and background settings with callback wiring', () => {
+    const props = renderPanelDock({
+      isZoomMenuOpen: true,
+      isBackgroundSettingsOpen: true,
+    });
+
+    fireEvent.click(screen.getByRole('menuitem', { name: '缩放至50%' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '显示画布所有元素' }));
+
+    expect(props.onUpdateScaleFromCenter).toHaveBeenCalledWith(0.5);
+    expect(props.onFitLayers).toHaveBeenCalledTimes(1);
+    expect(props.onCloseZoomMenu).toHaveBeenCalledTimes(2);
+
+    const panel = screen.getByRole('dialog', { name: '画布背景设置' });
+
+    fireEvent.click(within(panel).getByRole('button', { name: '暖灰' }));
+    fireEvent.change(within(panel).getByLabelText('自定义画布背景色'), {
+      target: { value: '#ffffff' },
+    });
+    fireEvent.change(within(panel).getByLabelText('画布背景十六进制颜色'), {
+      target: { value: '#abc' },
+    });
+    fireEvent.click(within(panel).getByRole('button', { name: '恢复默认' }));
+    fireEvent.click(within(panel).getByRole('button', { name: '关闭画布背景设置' }));
+
+    expect(props.onApplyCanvasBackgroundColor).toHaveBeenCalledWith('#f3f0ea');
+    expect(props.onApplyCanvasBackgroundColor).toHaveBeenCalledWith('#ffffff');
+    expect(props.onCanvasBackgroundHexChange).toHaveBeenCalledWith('#abc');
+    expect(props.onApplyCanvasBackgroundColor).toHaveBeenCalledWith('#f8fafc');
+    expect(props.onToggleBackgroundSettings).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasPanelDockView.tsx b/src/components/image-editor/ImageCanvasPanelDockView.tsx
new file mode 100644
index 000000000..b212ab8fd
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasPanelDockView.tsx
@@ -0,0 +1,318 @@
+import {
+  ImagePlus,
+  Layers,
+  Map as MapIcon,
+  Redo2,
+  RotateCcw,
+  Undo2,
+  X,
+} from 'lucide-react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+
+import { PlatformFloatingMenu, PlatformFloatingMenuItem } from '../common/PlatformFloatingMenu';
+import { PlatformIconButton } from '../common/PlatformIconButton';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type { StageMinimapModel } from './ImageCanvasInteractionModel';
+import {
+  CANVAS_BACKGROUND_OPTIONS,
+  DEFAULT_CANVAS_BACKGROUND_COLOR,
+  formatPercent,
+} from './ImageCanvasEditorModel';
+import type { CanvasViewport, SidebarPanel } from './ImageCanvasEditorTypes';
+
+type ImageCanvasPanelDockViewProps = {
+  viewport: CanvasViewport;
+  canvasBackgroundColor: string;
+  canvasBackgroundHexValue: string;
+  canUndo: boolean;
+  canRedo: boolean;
+  isZoomMenuOpen: boolean;
+  isBackgroundSettingsOpen: boolean;
+  activeSidebarPanel: SidebarPanel | null;
+  isMinimapOpen: boolean;
+  minimapModel: StageMinimapModel | null;
+  onFitLayers: () => void;
+  onUndoCanvasChange: () => void;
+  onRedoCanvasChange: () => void;
+  onUpdateScaleFromCenter: (nextScale: number) => void;
+  onToggleZoomMenu: () => void;
+  onCloseZoomMenu: () => void;
+  onToggleBackgroundSettings: () => void;
+  onApplyCanvasBackgroundColor: (color: string) => void;
+  onCanvasBackgroundHexChange: (value: string) => void;
+  onToggleSidebarPanel: (panel: SidebarPanel) => void;
+  onToggleMinimap: () => void;
+  onMinimapPointerDown: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+};
+
+export function ImageCanvasPanelDockView({
+  viewport,
+  canvasBackgroundColor,
+  canvasBackgroundHexValue,
+  canUndo,
+  canRedo,
+  isZoomMenuOpen,
+  isBackgroundSettingsOpen,
+  activeSidebarPanel,
+  isMinimapOpen,
+  minimapModel,
+  onFitLayers,
+  onUndoCanvasChange,
+  onRedoCanvasChange,
+  onUpdateScaleFromCenter,
+  onToggleZoomMenu,
+  onCloseZoomMenu,
+  onToggleBackgroundSettings,
+  onApplyCanvasBackgroundColor,
+  onCanvasBackgroundHexChange,
+  onToggleSidebarPanel,
+  onToggleMinimap,
+  onMinimapPointerDown,
+}: ImageCanvasPanelDockViewProps) {
+  return (
+    <>
+      <EditorIconButton
+        className="image-canvas-editor__reset-button"
+        label="重置画布视图"
+        title="重置画布视图"
+        icon={RotateCcw}
+        onClick={() => onFitLayers()}
+      />
+
+      <div
+        className="image-canvas-editor__panel-dock"
+        role="toolbar"
+        aria-label="画布面板入口"
+        onPointerDown={(event) => event.stopPropagation()}
+      >
+        <EditorIconButton
+          label="撤销"
+          title="撤销"
+          icon={Undo2}
+          disabled={!canUndo}
+          onClick={onUndoCanvasChange}
+        />
+        <EditorIconButton
+          label="重做"
+          title="重做"
+          icon={Redo2}
+          disabled={!canRedo}
+          onClick={onRedoCanvasChange}
+        />
+        <div className="image-canvas-editor__zoom-menu-wrap">
+          <PlatformInlineOptionButton
+            className="image-canvas-editor__zoom-trigger"
+            aria-label={`当前缩放比例 ${formatPercent(viewport.scale)}`}
+            aria-haspopup="menu"
+            aria-expanded={isZoomMenuOpen}
+            onClick={onToggleZoomMenu}
+          >
+            {formatPercent(viewport.scale)}
+          </PlatformInlineOptionButton>
+          {isZoomMenuOpen ? (
+            <PlatformFloatingMenu label="缩放菜单" placement="top-start">
+              <PlatformFloatingMenuItem
+                className="image-canvas-editor__zoom-menu-item"
+                onClick={() => {
+                  onUpdateScaleFromCenter(viewport.scale * 1.16);
+                  onCloseZoomMenu();
+                }}
+              >
+                放大
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                className="image-canvas-editor__zoom-menu-item"
+                onClick={() => {
+                  onUpdateScaleFromCenter(viewport.scale * 0.86);
+                  onCloseZoomMenu();
+                }}
+              >
+                缩小
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                className="image-canvas-editor__zoom-menu-item"
+                onClick={() => {
+                  onFitLayers();
+                  onCloseZoomMenu();
+                }}
+              >
+                显示画布所有元素
+              </PlatformFloatingMenuItem>
+              {[0.5, 1, 2].map((scale) => (
+                <PlatformFloatingMenuItem
+                  key={scale}
+                  className="image-canvas-editor__zoom-menu-item"
+                  onClick={() => {
+                    onUpdateScaleFromCenter(scale);
+                    onCloseZoomMenu();
+                  }}
+                >
+                  缩放至{Math.round(scale * 100)}%
+                </PlatformFloatingMenuItem>
+              ))}
+            </PlatformFloatingMenu>
+          ) : null}
+        </div>
+        <div className="image-canvas-editor__background-control">
+          <PlatformIconButton
+            label="画布背景色"
+            title="画布背景色"
+            aria-expanded={isBackgroundSettingsOpen}
+            onClick={onToggleBackgroundSettings}
+            icon={
+              <span
+                className="image-canvas-editor__background-swatch-current"
+                style={{ backgroundColor: canvasBackgroundColor }}
+              />
+            }
+          />
+          {isBackgroundSettingsOpen ? (
+            <div
+              className="image-canvas-editor__background-panel"
+              role="dialog"
+              aria-label="画布背景设置"
+            >
+              <div className="image-canvas-editor__background-panel-head">
+                <span>画布背景</span>
+                <button
+                  type="button"
+                  className="image-canvas-editor__background-close"
+                  aria-label="关闭画布背景设置"
+                  onClick={onToggleBackgroundSettings}
+                >
+                  <X className="h-4 w-4" aria-hidden="true" />
+                </button>
+              </div>
+              <div className="image-canvas-editor__background-current-row">
+                <span
+                  className="image-canvas-editor__background-current-preview"
+                  style={{ backgroundColor: canvasBackgroundColor }}
+                  aria-hidden="true"
+                />
+                <span>{canvasBackgroundColor}</span>
+              </div>
+              <label className="image-canvas-editor__background-spectrum">
+                <input
+                  type="color"
+                  aria-label="画布背景色相"
+                  value={canvasBackgroundColor}
+                  onChange={(event) =>
+                    onApplyCanvasBackgroundColor(event.currentTarget.value)
+                  }
+                />
+                <span
+                  className="image-canvas-editor__background-spectrum-surface"
+                  aria-hidden="true"
+                />
+                <span
+                  className="image-canvas-editor__background-spectrum-handle"
+                  aria-hidden="true"
+                />
+              </label>
+              <label className="image-canvas-editor__background-hue">
+                <input
+                  type="color"
+                  aria-label="自定义画布背景色"
+                  value={canvasBackgroundColor}
+                  onChange={(event) =>
+                    onApplyCanvasBackgroundColor(event.currentTarget.value)
+                  }
+                />
+              </label>
+              <div
+                className="image-canvas-editor__background-presets"
+                aria-label="画布背景预设色"
+              >
+                {CANVAS_BACKGROUND_OPTIONS.map((option) => (
+                  <button
+                    key={option.value}
+                    type="button"
+                    className="image-canvas-editor__background-preset"
+                    aria-label={option.label}
+                    aria-pressed={canvasBackgroundColor === option.value}
+                    onClick={() => onApplyCanvasBackgroundColor(option.value)}
+                  >
+                    <span
+                      className="image-canvas-editor__background-swatch"
+                      style={{ backgroundColor: option.value }}
+                    />
+                  </button>
+                ))}
+              </div>
+              <div className="image-canvas-editor__background-footer">
+                <label className="image-canvas-editor__background-hex-field">
+                  <span>HEX</span>
+                  <input
+                    aria-label="画布背景十六进制颜色"
+                    value={canvasBackgroundHexValue}
+                    spellCheck={false}
+                    onChange={(event) =>
+                      onCanvasBackgroundHexChange(event.currentTarget.value)
+                    }
+                  />
+                </label>
+                <button
+                  type="button"
+                  className="image-canvas-editor__background-reset"
+                  onClick={() =>
+                    onApplyCanvasBackgroundColor(DEFAULT_CANVAS_BACKGROUND_COLOR)
+                  }
+                >
+                  <RotateCcw className="h-3.5 w-3.5" aria-hidden="true" />
+                  恢复默认
+                </button>
+              </div>
+            </div>
+          ) : null}
+        </div>
+        <EditorIconButton
+          label="打开素材"
+          title="素材"
+          icon={ImagePlus}
+          pressed={activeSidebarPanel === 'assets'}
+          onClick={() => onToggleSidebarPanel('assets')}
+        />
+        <EditorIconButton
+          label="打开图层"
+          title="图层"
+          icon={Layers}
+          pressed={activeSidebarPanel === 'layers'}
+          onClick={() => onToggleSidebarPanel('layers')}
+        />
+        <EditorIconButton
+          label="切换小地图"
+          title="小地图"
+          icon={MapIcon}
+          pressed={isMinimapOpen}
+          onClick={onToggleMinimap}
+        />
+      </div>
+
+      {isMinimapOpen && minimapModel ? (
+        <button
+          type="button"
+          className="image-canvas-editor__minimap"
+          aria-label="画布小地图"
+          title="拖拽移动视图"
+          onPointerDown={onMinimapPointerDown}
+        >
+          <span className="image-canvas-editor__minimap-stage">
+            {minimapModel.layers.map((layer) => (
+              <span
+                key={layer.id}
+                className="image-canvas-editor__minimap-layer"
+                title={layer.title}
+                style={layer.rect}
+              />
+            ))}
+            <span
+              className="image-canvas-editor__minimap-viewport"
+              style={minimapModel.viewport}
+            />
+          </span>
+        </button>
+      ) : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx b/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx
new file mode 100644
index 000000000..98e329cb2
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx
@@ -0,0 +1,315 @@
+import { ImagePlus } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+
+import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import type {
+  CharacterReferenceImage,
+  GenerateDialogState,
+  PublicationMaterialsGameInfo,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import {
+  buildPublicationMaterialsPrompt,
+  calculateEditorImageModelPrice,
+  DEFAULT_PUBLICATION_GAME_INFO,
+} from './ImageCanvasGenerationModel';
+import type { PublicationMaterialsWorkflow } from './ImageCanvasPublicationMaterialsModel';
+
+type ImageCanvasPublicationMaterialsDemoPanelViewProps = {
+  dialog: GenerateDialogState;
+  workflow: PublicationMaterialsWorkflow;
+  style: CSSProperties;
+  publicationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  isPublicationReferenceMenuOpen: boolean;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setIsPublicationReferenceMenuOpen: Dispatch<SetStateAction<boolean>>;
+  setIsPickingPublicationReferenceFromCanvas: Dispatch<SetStateAction<boolean>>;
+  renderEditorPortal: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onRequestUpload: (target: UploadTarget) => void;
+  onRememberImageModel: (model: string) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+
+function resetFailedDialogStatus(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+function updatePublicationGameInfoField(
+  currentDialog: GenerateDialogState | null,
+  key: keyof PublicationMaterialsGameInfo,
+  value: string,
+): GenerateDialogState | null {
+  if (currentDialog?.mode !== 'publication') {
+    return currentDialog;
+  }
+  const publicationGameInfo = {
+    ...DEFAULT_PUBLICATION_GAME_INFO,
+    ...currentDialog.publicationGameInfo,
+    [key]: value,
+  };
+  return {
+    ...resetFailedDialogStatus(currentDialog),
+    publicationGameInfo,
+    prompt: buildPublicationMaterialsPrompt(publicationGameInfo),
+  };
+}
+
+function ReferenceThumb({
+  reference,
+  index,
+  onRemove,
+}: {
+  reference: CharacterReferenceImage;
+  index: number;
+  onRemove: () => void;
+}) {
+  const label = reference.label || `参考图${index + 1}`;
+  return (
+    <ImageCanvasReferenceSlot
+      tone="default"
+      icon={<ImagePlus className="h-4 w-4" aria-hidden="true" />}
+      imageSrc={reference.src}
+      label={label}
+      ariaLabel={label}
+      title={reference.label}
+      onRemove={onRemove}
+      removeLabel={`删除${label}`}
+    />
+  );
+}
+
+export function ImageCanvasPublicationMaterialsDemoPanelView({
+  dialog,
+  workflow,
+  style,
+  publicationReferenceButtonRef,
+  isPublicationReferenceMenuOpen,
+  setGenerateDialog,
+  setIsPublicationReferenceMenuOpen,
+  setIsPickingPublicationReferenceFromCanvas,
+  renderEditorPortal,
+  buildPortalMenuStyle,
+  onRequestUpload,
+  onRememberImageModel,
+  onSubmit,
+}: ImageCanvasPublicationMaterialsDemoPanelViewProps) {
+  const references = dialog.publicationReferences ?? [];
+  const publicationGameInfo = {
+    ...DEFAULT_PUBLICATION_GAME_INFO,
+    ...dialog.publicationGameInfo,
+  };
+  return (
+    <form
+      className="image-canvas-editor__character-composer image-canvas-editor__publication-composer"
+      style={style}
+      role="dialog"
+      aria-label={`${workflow.label}生成卡片`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (dialog.status !== 'generating') {
+          onSubmit(dialog);
+        }
+      }}
+    >
+      <div className="image-canvas-editor__reference-strip">
+        {references.map((reference, index) => (
+          <ReferenceThumb
+            key={reference.id}
+            reference={reference}
+            index={index}
+            onRemove={() =>
+              setGenerateDialog((currentDialog) =>
+                currentDialog?.mode === 'publication'
+                  ? {
+                      ...resetFailedDialogStatus(currentDialog),
+                      publicationReferences: (
+                        currentDialog.publicationReferences ?? []
+                      ).filter((item) => item.id !== reference.id),
+                    }
+                  : currentDialog,
+              )
+            }
+          />
+        ))}
+        <ImageCanvasReferenceSlot
+          buttonRef={publicationReferenceButtonRef}
+          tone="default"
+          icon={<ImagePlus className="h-4 w-4" aria-hidden="true" />}
+          label="添加参考图"
+          ariaLabel="添加参考图"
+          disabled={dialog.status === 'generating'}
+          isAdd
+          onClick={() => setIsPublicationReferenceMenuOpen((open) => !open)}
+        />
+        {isPublicationReferenceMenuOpen
+          ? renderEditorPortal(
+              <PlatformFloatingMenu
+                className="image-canvas-editor__publication-reference-menu image-canvas-editor__portal-menu"
+                label="宣发素材参考图来源"
+                placement="top-start"
+                style={buildPortalMenuStyle(
+                  publicationReferenceButtonRef.current,
+                  'above',
+                )}
+              >
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsPickingPublicationReferenceFromCanvas(true);
+                    setIsPublicationReferenceMenuOpen(false);
+                  }}
+                >
+                  从画布中选择
+                </PlatformFloatingMenuItem>
+                <PlatformFloatingMenuItem
+                  className="image-canvas-editor__context-menu-item"
+                  onClick={() => {
+                    setIsPublicationReferenceMenuOpen(false);
+                    onRequestUpload('publication-reference');
+                  }}
+                >
+                  上传图片
+                </PlatformFloatingMenuItem>
+              </PlatformFloatingMenu>,
+            )
+          : null}
+      </div>
+
+      <div className="image-canvas-editor__publication-composer-fields">
+        <div className="image-canvas-editor__publication-composer-summary">
+          <span>{workflow.outputLabel}</span>
+          <strong>{workflow.sizeLabel}</strong>
+        </div>
+        <label className="image-canvas-editor__field-block">
+          <PlatformFieldLabel
+            variant="field"
+            className="image-canvas-editor__field-title"
+          >
+            游戏名
+          </PlatformFieldLabel>
+          <PlatformTextField
+            aria-label={`${workflow.label}游戏名`}
+            value={publicationGameInfo.gameName}
+            disabled={dialog.status === 'generating'}
+            placeholder="马戏团午夜惊魂"
+            size="sm"
+            density="compact"
+            className="image-canvas-editor__publication-input"
+            onChange={(event) =>
+              setGenerateDialog((currentDialog) =>
+                updatePublicationGameInfoField(
+                  currentDialog,
+                  'gameName',
+                  event.target.value,
+                ),
+              )
+            }
+          />
+        </label>
+        <label className="image-canvas-editor__field-block">
+          <PlatformFieldLabel
+            variant="field"
+            className="image-canvas-editor__field-title"
+          >
+            游戏分类
+          </PlatformFieldLabel>
+          <PlatformTextField
+            aria-label={`${workflow.label}游戏分类`}
+            value={publicationGameInfo.gameCategories}
+            disabled={dialog.status === 'generating'}
+            placeholder="非对称对抗"
+            size="sm"
+            density="compact"
+            className="image-canvas-editor__publication-input"
+            onChange={(event) =>
+              setGenerateDialog((currentDialog) =>
+                updatePublicationGameInfoField(
+                  currentDialog,
+                  'gameCategories',
+                  event.target.value,
+                ),
+              )
+            }
+          />
+        </label>
+        <label className="image-canvas-editor__field-block image-canvas-editor__publication-description-field">
+          <PlatformFieldLabel
+            variant="field"
+            className="image-canvas-editor__field-title"
+          >
+            一句话描述游戏
+          </PlatformFieldLabel>
+          <PlatformTextField
+            variant="textarea"
+            aria-label={`${workflow.label}一句话描述游戏`}
+            value={publicationGameInfo.gameDescription}
+            disabled={dialog.status === 'generating'}
+            placeholder="神奇数字马戏团里，帕姆尼失控了，找到钥匙，开门逃离马戏团，千万别被抓住了"
+            size="sm"
+            density="compact"
+            className="image-canvas-editor__publication-description"
+            onChange={(event) =>
+              setGenerateDialog((currentDialog) =>
+                updatePublicationGameInfoField(
+                  currentDialog,
+                  'gameDescription',
+                  event.target.value,
+                ),
+              )
+            }
+          />
+        </label>
+      </div>
+
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+
+      <div className="image-canvas-editor__generation-composer-footer">
+        <ImageCanvasGenerationImageOptionsView
+          dialog={dialog}
+          setGenerateDialog={setGenerateDialog}
+          includeDimensions={false}
+          onRememberImageModel={onRememberImageModel}
+          optionLabelPrefix="宣发素材"
+          cost={calculateEditorImageModelPrice(dialog.imageModel)}
+          submitLabel="生成"
+          submitAriaLabel="生成"
+          renderEditorPortal={renderEditorPortal}
+          buildPortalMenuStyle={buildPortalMenuStyle}
+        />
+      </div>
+    </form>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasPublicationMaterialsModel.ts b/src/components/image-editor/ImageCanvasPublicationMaterialsModel.ts
new file mode 100644
index 000000000..b5ba83f84
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasPublicationMaterialsModel.ts
@@ -0,0 +1,136 @@
+import type { PublicationMaterialsWorkflowId } from './ImageCanvasEditorTypes';
+
+export type PublicationMaterialsWorkflow = {
+  id: PublicationMaterialsWorkflowId;
+  label: string;
+  promptLabel?: string;
+  englishName: string;
+  outputLabel: string;
+  sizeLabel: string;
+  outputSize: string;
+  aspectRatio: string;
+  imageSize: string;
+  scenario: string;
+  fields: string[];
+  framework: string[];
+  promptConstraints: string[];
+  referenceConstraints: string[];
+  postProcessConstraints: string[];
+};
+
+export const PUBLICATION_MATERIALS_WORKFLOWS: PublicationMaterialsWorkflow[] = [
+  {
+    id: 'publication-cover-image',
+    label: '游戏首图',
+    englishName: 'Home Image',
+    outputLabel: '单张主视觉',
+    sizeLabel: '720 x 540',
+    outputSize: '720x540',
+    aspectRatio: '4:3',
+    imageSize: '1K',
+    scenario: '推荐流、作品卡和首屏传播位',
+    fields: ['游戏名称', '玩法分类标签', '一句话玩法', '主视觉关键词', '必要文字'],
+    framework: [
+      '读取游戏基础信息和现有参考图',
+      '抽取核心玩法动作、主体物和城市/题材符号',
+      '生成一张带标题文字的横版主视觉',
+      '按首图尺寸、文字可读性和主体完整度验收',
+    ],
+    promptConstraints: [
+      '标题文字必须直接进入画面，优先使用游戏名称；标题应为清晰中文大字，少字、醒目、可读',
+      '画面只表达一个强主题，不拼贴多张小图，不做详情页合集，不做截图说明页',
+      '主体、玩法道具和背景层级必须清楚；核心主体适合小尺寸推荐卡，缩小后仍能一眼识别',
+      '标题与主体不能互相遮挡；主体不裁切，标题不贴边，四周保留安全边距',
+      '避免暗黑、脏污、低清、廉价拼贴、文字乱码、伪文字、英文标题、非中文标题、错误游戏名',
+    ],
+    referenceConstraints: [
+      '参考图只用于提取视觉约束：主体、玩法元素、色彩气质、画风、构图方向；不得照搬水印、边框、无关 UI、平台外壳或隐私信息',
+    ],
+    postProcessConstraints: [
+      '输出检查：720 x 540，4:3；主体完整不裁切；标题清晰可读；画面只有一个主视觉重点',
+      '输出 metadata 记录完整提示词、尺寸和参考图摘要',
+      '不做真实发布、不写作品数据，只作为画布素材候选',
+    ],
+  },
+  {
+    id: 'publication-detail-gallery',
+    label: '详情五图',
+    promptLabel: '详情页单图',
+    englishName: 'Detail Gallery',
+    outputLabel: '单张详情图',
+    sizeLabel: '720 x 1280',
+    outputSize: '720x1280',
+    aspectRatio: '9:16',
+    imageSize: '1K',
+    scenario: '作品详情、应用介绍和运营分发图组',
+    fields: ['游戏名称', '玩法分类标签', '卖点拆解', '图组顺序', '必要文字'],
+    framework: [
+      '选择当前这张详情图要表达的单一卖点',
+      '生成一张带短标题的竖版详情页素材',
+      '让主体、玩法反馈和背景符号保持同一套游戏物料气质',
+      '按单图尺寸、标题可读性、主体完整度和非合集画面验收',
+    ],
+    promptConstraints: [
+      '本次只生成一张 720 x 1280 竖版详情图；不要把五张图合成一张长图、拼图、多分镜合集或截图说明页',
+      '每张图只承载一个卖点，短标题必须直接出现在画面中；标题用简短中文，不堆长句',
+      '画面保持与同一游戏后续详情图可组成一套：同一游戏名、同一主体物件体系、同一画风、同一色彩气质',
+      '构图要服务当前单一卖点，主体、玩法道具、反馈效果和背景层级清楚；核心信息缩小后仍能识别',
+      '短标题不能遮挡核心主体和玩法反馈；避免文字过密、小字不可读、UI 挡主体',
+      '连续生成多张详情图时，可以独立生成并允许顺序差异；同一批次复用同一份参考摘要，主动拉开角度、主体姿势和背景变化',
+      '避免五联图、分栏、多格漫画、长图合集、重复小图拼贴、文字乱码、伪文字、英文标题、非中文标题',
+    ],
+    referenceConstraints: [
+      '从参考图解析并统一：画风、主体物件、玩法道具、背景符号、地域/场景元素、色板和光影氛围',
+      '参考图只作为视觉理解来源，不照搬截图 UI、水印、边框、按钮、状态栏、弹窗或无关文字',
+    ],
+    postProcessConstraints: [
+      '输出检查：单张 720 x 1280 竖版；只表达一个卖点；标题不截断、不乱码；不是五图合集或拼贴',
+      'metadata 记录本张图的卖点、提示词和参考摘要',
+      '仅生成画布候选物料，不触发投放、分享或发布',
+    ],
+  },
+  {
+    id: 'publication-promo-poster',
+    label: '运营海报',
+    englishName: 'Promo Poster',
+    outputLabel: '单张活动海报',
+    sizeLabel: '1280 x 720',
+    outputSize: '1280x720',
+    aspectRatio: '16:9',
+    imageSize: '1K',
+    scenario: '社群、活动、渠道投放和运营节日位',
+    fields: ['游戏名称', '活动主题', '玩法标签', '主文案', '行动指令'],
+    framework: [
+      '确认运营主题和投放场景',
+      '抽取游戏核心视觉符号和活动情绪',
+      '生成带主标题、卖点和行动指令的海报',
+      '按传播可读性、品牌一致性和尺寸验收',
+    ],
+    promptConstraints: [
+      '主标题、游戏名和行动指令必须清晰入画；三者要有明确层级，不能互相抢占',
+      '运营氛围可以更强，包括活动感、福利感、节日感、更新感，但不能脱离游戏玩法、主体物件和美术资产',
+      '版式必须预留二维码或平台标识位置，但不得生成假二维码、假平台 Logo、假按钮或不可识别图标',
+      '右下角必须保留一个干净的白色二维码留白方块，并在方块内部上方用黑色小字写“此处换上你的游戏二维码”；留白内不要生成假二维码',
+      '活动主题优先级高于普通详情介绍，但不得覆盖游戏识别；用户仍需一眼知道这是哪款游戏、什么玩法',
+      '避免夸张承诺、敏感营销词、虚假福利、价格折扣、具体日期、不可读小字、文字乱码、伪文字',
+    ],
+    referenceConstraints: [
+      '参考图用于锁定角色/主体物件、玩法道具、地域/场景符号、色彩气质和画风，不照搬参考图中的 UI、水印、边框或无关文字',
+    ],
+    postProcessConstraints: [
+      '输出检查：16:9 横版 720p，建议 1280 x 720；主标题最大，游戏名清楚，行动指令可读；右下角白色二维码留白方块干净，方块内部上方带有黑色小字“此处换上你的游戏二维码”',
+      'metadata 记录活动主题、文案、提示词和预留位说明',
+      '仅生成画布候选物料，不触发投放、分享或发布',
+    ],
+  },
+];
+
+export function getPublicationMaterialsWorkflow(
+  workflowId: PublicationMaterialsWorkflowId,
+): PublicationMaterialsWorkflow {
+  return (
+    PUBLICATION_MATERIALS_WORKFLOWS.find(
+      (workflow) => workflow.id === workflowId,
+    ) ?? PUBLICATION_MATERIALS_WORKFLOWS[0]!
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx
new file mode 100644
index 000000000..7639dcb72
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx
@@ -0,0 +1,255 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasLayer,
+  CharacterReferenceImage,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasQuickEditPanelView } from './ImageCanvasQuickEditPanelView';
+
+function createLayer(): CanvasLayer {
+  return {
+    id: 'layer-a',
+    resourceId: 'resource-a',
+    title: '源图',
+    src: 'data:image/png;base64,c291cmNl',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 180,
+    originalWidth: 320,
+    originalHeight: 180,
+    zIndex: 1,
+    sourceType: 'uploaded',
+  };
+}
+
+function QuickEditPanelHarness({
+  initialPanel,
+  onSubmit = vi.fn(),
+  onRequestUpload = vi.fn(),
+  onRememberImageModel = vi.fn(),
+}: {
+  initialPanel: QuickEditPanelState;
+  onSubmit?: () => void;
+  onRequestUpload?: (target: 'quick-edit-reference') => void;
+  onRememberImageModel?: (model: string) => void;
+}) {
+  const [panel, setPanel] = useState<QuickEditPanelState | null>(initialPanel);
+  const [isReferenceMenuOpen, setIsReferenceMenuOpen] = useState(false);
+  const [isPickingReference, setIsPickingReference] = useState(false);
+  const referenceButtonRef = useRef<HTMLButtonElement | null>(null);
+
+  return panel ? (
+    <div>
+      <ImageCanvasQuickEditPanelView
+        panel={panel}
+        sourceLayer={createLayer()}
+        style={{ left: 10, top: 20 }}
+        referenceButtonRef={referenceButtonRef}
+        isReferenceMenuOpen={isReferenceMenuOpen}
+        setIsReferenceMenuOpen={setIsReferenceMenuOpen}
+        setIsPickingQuickEditReferenceFromCanvas={setIsPickingReference}
+        renderEditorPortal={(node) => node}
+        onRequestUpload={onRequestUpload}
+        onRememberImageModel={onRememberImageModel}
+        setQuickEditPanel={setPanel}
+        onSubmit={onSubmit}
+      />
+      <output aria-label="当前提示词">{panel.prompt}</output>
+      <output aria-label="当前尺寸">{panel.size}</output>
+      <output aria-label="当前比例">{panel.aspectRatio ?? '-'}</output>
+      <output aria-label="当前图片规格">{panel.imageSize ?? '-'}</output>
+      <output aria-label="当前模型">{panel.model}</output>
+      <output aria-label="当前状态">{panel.status}</output>
+      <output aria-label="当前错误">{panel.errorMessage ?? '-'}</output>
+      <output aria-label="参考图数量">
+        {panel.quickEditReferences?.length ?? 0}
+      </output>
+      <output aria-label="画布选择参考图">
+        {isPickingReference ? 'picking' : 'idle'}
+      </output>
+    </div>
+  ) : (
+    <output aria-label="面板状态">closed</output>
+  );
+}
+
+describe('ImageCanvasQuickEditPanelView', () => {
+  it('updates prompt and clears failed state while keeping options editable', () => {
+    const rememberImageModel = vi.fn();
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '旧提示',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gemini-3.1-flash-image-preview',
+          status: 'failed',
+          errorMessage: '失败原因',
+        }}
+        onRememberImageModel={rememberImageModel}
+      />,
+    );
+
+    fireEvent.change(screen.getByLabelText('快速编辑提示词'), {
+      target: { value: '新提示' },
+    });
+
+    expect(screen.getByLabelText('当前提示词').textContent).toBe('新提示');
+    expect(screen.getByLabelText('当前尺寸').textContent).toBe('1024x1024');
+    expect(screen.getByLabelText('当前模型').textContent).toBe(
+      'gemini-3.1-flash-image-preview',
+    );
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑尺寸 1:1·1K' }));
+    fireEvent.click(screen.getByRole('button', { name: '比例 16:9' }));
+    fireEvent.click(screen.getByRole('button', { name: '尺寸 2K' }));
+    expect(screen.getByLabelText('当前比例').textContent).toBe('16:9');
+    expect(screen.getByLabelText('当前图片规格').textContent).toBe('2K');
+
+    fireEvent.click(screen.getByRole('button', { name: '快速编辑模型 nanobanana2' }));
+    fireEvent.click(screen.getByRole('button', { name: 'gpt-image-2' }));
+    expect(screen.getByLabelText('当前模型').textContent).toBe('gpt-image-2');
+    expect(rememberImageModel).toHaveBeenCalledWith('gpt-image-2');
+  });
+
+  it('submits without rendering a standalone close button', () => {
+    const submitQuickEdit = vi.fn();
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '提示',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'nano',
+          status: 'idle',
+        }}
+        onSubmit={submitQuickEdit}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+    expect(submitQuickEdit).toHaveBeenCalledTimes(1);
+    expect(
+      screen.queryByRole('button', { name: '关闭快速编辑图片' }),
+    ).toBeNull();
+  });
+
+  it('shows configured mud point price inside redraw submit button', () => {
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '重绘提示',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gpt-image-2',
+          status: 'idle',
+          mode: 'redraw',
+        }}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: '生成' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('renders only extra references and keeps the implicit source image out of the strip', () => {
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '把原图改成雨天',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gpt-image-2',
+          status: 'failed',
+          errorMessage: '失败原因',
+          quickEditReferences: [
+            { id: 'ref-1', label: '天空参考', src: '/sky.png' },
+          ],
+        }}
+      />,
+    );
+
+    expect(screen.getByLabelText('图1')).toBeTruthy();
+    expect(screen.queryByLabelText('原图 图2')).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '删除图1' }));
+
+    expect(screen.getByLabelText('参考图数量').textContent).toBe('0');
+    expect(screen.getByLabelText('当前状态').textContent).toBe('idle');
+    expect(screen.getByLabelText('当前错误').textContent).toBe('-');
+    expect(screen.queryByLabelText('原图 图1')).toBeNull();
+  });
+
+  it('opens reference source menu and dispatches canvas picking or upload actions', () => {
+    const requestUpload = vi.fn();
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '提示',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gpt-image-2',
+          status: 'idle',
+          quickEditReferences: [],
+        }}
+        onRequestUpload={requestUpload}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '添加快速编辑参考图' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '从画布中选择' }));
+    expect(screen.getByLabelText('画布选择参考图').textContent).toBe('picking');
+
+    fireEvent.click(screen.getByRole('button', { name: '添加快速编辑参考图' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: '上传图片' }));
+    expect(requestUpload).toHaveBeenCalledWith('quick-edit-reference');
+    expect(screen.getByLabelText('画布选择参考图').textContent).toBe('idle');
+  });
+
+  it('disables adding quick edit references after eight extra images', () => {
+    render(
+      <QuickEditPanelHarness
+        initialPanel={{
+          sourceLayerId: 'layer-a',
+          prompt: '提示',
+          size: '1024x1024',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          model: 'gpt-image-2',
+          status: 'idle',
+          quickEditReferences: Array.from({ length: 8 }, (_, index) => ({
+            id: `ref-${index}`,
+            label: `参考${index + 1}`,
+            src: `/ref-${index}.png`,
+          })) satisfies CharacterReferenceImage[],
+        }}
+      />,
+    );
+
+    expect(
+      (screen.getByRole('button', {
+        name: '添加快速编辑参考图',
+      }) as HTMLButtonElement).disabled,
+    ).toBe(true);
+    expect(screen.queryByLabelText('原图 图9')).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx
new file mode 100644
index 000000000..50ab854ac
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasQuickEditPanelView.tsx
@@ -0,0 +1,488 @@
+import { Check, ChevronDown, Cpu, ImageIcon, ImagePlus } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import type {
+  CanvasLayer,
+  CharacterReferenceImage,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import {
+  calculateEditorImageModelPrice,
+  EDITOR_IMAGE_DIMENSION_OPTIONS,
+  EDITOR_IMAGE_MODEL_OPTIONS,
+  getEditorImageModelDisplayName,
+  IMAGE_MODEL_NANOBANANA2,
+  normalizeEditorImageModel,
+  QUICK_EDIT_REFERENCE_LIMIT,
+  resolveEditorImageSizeLabel,
+} from './ImageCanvasGenerationModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasQuickEditPanelViewProps = {
+  panel: QuickEditPanelState;
+  sourceLayer: CanvasLayer;
+  style: CSSProperties;
+  referenceButtonRef?: RefObject<HTMLButtonElement | null>;
+  isReferenceMenuOpen?: boolean;
+  setIsReferenceMenuOpen?: Dispatch<SetStateAction<boolean>>;
+  setIsPickingQuickEditReferenceFromCanvas?: Dispatch<SetStateAction<boolean>>;
+  setQuickEditPanel: Dispatch<SetStateAction<QuickEditPanelState | null>>;
+  renderEditorPortal?: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle?: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onRequestUpload?: (target: 'quick-edit-reference') => void;
+  onRememberImageModel?: (model: string) => void;
+  onSubmit: () => void;
+};
+
+type OpenPanel = 'dimensions' | 'model' | null;
+
+function resetFailedPanelStatus<T extends { status: string; errorMessage?: string }>(
+  panel: T,
+) {
+  return {
+    ...panel,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+  };
+}
+
+function QuickEditReferenceChip({
+  reference,
+  index,
+  onRemove,
+}: {
+  reference: CharacterReferenceImage;
+  index: number;
+  onRemove: () => void;
+}) {
+  const label = `图${index + 1}`;
+  return (
+    <ImageCanvasReferenceSlot
+      tone="quick-edit"
+      icon={<ImageIcon className="h-4 w-4" aria-hidden="true" />}
+      imageSrc={reference.src}
+      label={label}
+      ariaLabel={label}
+      title={reference.label}
+      onRemove={onRemove}
+      removeLabel={`删除${label}`}
+    />
+  );
+}
+
+function getImageDimensionOptions(model: string | null | undefined) {
+  return (
+    EDITOR_IMAGE_DIMENSION_OPTIONS[
+      (normalizeEditorImageModel(model) ??
+        IMAGE_MODEL_NANOBANANA2) as keyof typeof EDITOR_IMAGE_DIMENSION_OPTIONS
+    ] ?? EDITOR_IMAGE_DIMENSION_OPTIONS[IMAGE_MODEL_NANOBANANA2]
+  );
+}
+
+function getPanelAspectRatio(panel: QuickEditPanelState) {
+  const options = getImageDimensionOptions(panel.model);
+  const aspectRatios = options.aspectRatios as readonly string[];
+  return panel.aspectRatio && aspectRatios.includes(panel.aspectRatio)
+    ? panel.aspectRatio
+    : (options.aspectRatios[0] ?? '1:1');
+}
+
+function getPanelImageSize(panel: QuickEditPanelState) {
+  const options = getImageDimensionOptions(panel.model);
+  const imageSizes = options.imageSizes as readonly string[];
+  return panel.imageSize && imageSizes.includes(panel.imageSize)
+    ? panel.imageSize
+    : (options.imageSizes.find((size) => size === '1K') ??
+        options.imageSizes[0] ??
+        '1K');
+}
+
+function QuickEditOptionChoice({
+  children,
+  selected,
+  className,
+  ariaLabel,
+  onClick,
+}: {
+  children: ReactNode;
+  selected: boolean;
+  className?: string;
+  ariaLabel?: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className={['image-canvas-editor__option-popover-choice', className]
+        .filter(Boolean)
+        .join(' ')}
+      aria-pressed={selected}
+      aria-label={ariaLabel}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function ImageCanvasQuickEditPanelView({
+  panel,
+  style,
+  referenceButtonRef,
+  isReferenceMenuOpen = false,
+  setIsReferenceMenuOpen,
+  setIsPickingQuickEditReferenceFromCanvas,
+  setQuickEditPanel,
+  renderEditorPortal = (node) => node,
+  buildPortalMenuStyle = () => ({}),
+  onRequestUpload = () => {},
+  onRememberImageModel = () => {},
+  onSubmit,
+}: ImageCanvasQuickEditPanelViewProps) {
+  const [openPanel, setOpenPanel] = useState<OpenPanel>(null);
+  const dimensionsButtonRef = useRef<HTMLButtonElement | null>(null);
+  const modelButtonRef = useRef<HTMLButtonElement | null>(null);
+  const isRedraw = panel.mode === 'redraw';
+  const isGenerating = panel.status === 'generating';
+  const panelLabel = isRedraw ? '重绘图片' : '快速编辑图片';
+  const promptLabel = isRedraw ? '重绘提示词' : '快速编辑提示词';
+  const references = panel.quickEditReferences ?? [];
+  const selectedModel = normalizeEditorImageModel(panel.model);
+  const selectedModelLabel = getEditorImageModelDisplayName(selectedModel);
+  const dimensionOptions = getImageDimensionOptions(selectedModel);
+  const selectedAspectRatio = getPanelAspectRatio(panel);
+  const selectedImageSize = getPanelImageSize(panel);
+  const dimensionLabel = resolveEditorImageSizeLabel({
+    aspectRatio: selectedAspectRatio,
+    imageSize: selectedImageSize,
+  });
+  const canAddReferences =
+    !isRedraw && !isGenerating && references.length < QUICK_EDIT_REFERENCE_LIMIT;
+  const dismissOpenPanel = useCallback(() => setOpenPanel(null), []);
+
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: openPanel !== null,
+    boundaryRefs: [dimensionsButtonRef, modelButtonRef],
+    onDismiss: dismissOpenPanel,
+  });
+
+  const updatePanel = (patch: Partial<QuickEditPanelState>) => {
+    setQuickEditPanel((currentPanel) =>
+      currentPanel
+        ? {
+            ...resetFailedPanelStatus(currentPanel),
+            ...patch,
+          }
+        : currentPanel,
+    );
+  };
+
+  const updateModel = (model: string) => {
+    const nextOptions = getImageDimensionOptions(model);
+    const nextAspectRatios = nextOptions.aspectRatios as readonly string[];
+    const nextImageSizes = nextOptions.imageSizes as readonly string[];
+    onRememberImageModel(model);
+    setQuickEditPanel((currentPanel) => {
+      if (!currentPanel) {
+        return currentPanel;
+      }
+      return {
+        ...resetFailedPanelStatus(currentPanel),
+        model,
+        aspectRatio:
+          currentPanel.aspectRatio &&
+          nextAspectRatios.includes(currentPanel.aspectRatio)
+            ? currentPanel.aspectRatio
+            : (nextOptions.aspectRatios[0] ?? '1:1'),
+        imageSize:
+          currentPanel.imageSize && nextImageSizes.includes(currentPanel.imageSize)
+            ? currentPanel.imageSize
+            : (nextOptions.imageSizes.find((size) => size === '1K') ??
+              nextOptions.imageSizes[0]),
+      };
+    });
+  };
+
+  const togglePanel = (nextPanel: Exclude<OpenPanel, null>) => {
+    setOpenPanel((currentPanel) =>
+      currentPanel === nextPanel ? null : nextPanel,
+    );
+  };
+
+  return (
+    <>
+      <form
+        className="image-canvas-editor__quick-edit-panel image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image image-canvas-editor__generation-composer--quick-edit"
+        style={style}
+        role="dialog"
+        aria-label={panelLabel}
+        onPointerDown={(event) => event.stopPropagation()}
+        onSubmit={(event) => {
+          event.preventDefault();
+          onSubmit();
+        }}
+      >
+        <div className="image-canvas-editor__reference-strip">
+          {!isRedraw
+            ? references.map((reference, index) => (
+                <QuickEditReferenceChip
+                  key={reference.id}
+                  reference={reference}
+                  index={index}
+                  onRemove={() =>
+                    setQuickEditPanel((currentPanel) =>
+                      currentPanel
+                        ? {
+                            ...resetFailedPanelStatus(currentPanel),
+                            quickEditReferences: (
+                              currentPanel.quickEditReferences ?? []
+                            ).filter((item) => item.id !== reference.id),
+                          }
+                        : currentPanel,
+                    )
+                  }
+                />
+              ))
+            : null}
+          {!isRedraw ? (
+            <ImageCanvasReferenceSlot
+              buttonRef={referenceButtonRef}
+              tone="quick-edit"
+              icon={<ImagePlus className="h-4 w-4" aria-hidden="true" />}
+              label="参考图"
+              ariaLabel="添加快速编辑参考图"
+              disabled={!canAddReferences}
+              isAdd
+              onClick={() => setIsReferenceMenuOpen?.((open) => !open)}
+            />
+          ) : null}
+        </div>
+        <PlatformTextField
+          variant="textarea"
+          aria-label={promptLabel}
+          value={panel.prompt}
+          disabled={isGenerating}
+          size="sm"
+          density="compact"
+          className="image-canvas-editor__generation-prompt image-canvas-editor__quick-edit-prompt"
+          onChange={(event) =>
+            updatePanel({
+              prompt: event.target.value,
+            })
+          }
+        />
+        {panel.status === 'failed' ? (
+          <PlatformStatusMessage
+            tone="error"
+            surface="platform"
+            size="xs"
+            className="image-canvas-editor__generate-status"
+            role="alert"
+          >
+            {panel.errorMessage}
+          </PlatformStatusMessage>
+        ) : null}
+        <div className="image-canvas-editor__generation-composer-footer image-canvas-editor__quick-edit-footer">
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions">
+            <PlatformInlineOptionButton
+              ref={dimensionsButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+              aria-label={`${isRedraw ? '重绘' : '快速编辑'}尺寸 ${dimensionLabel}`}
+              aria-expanded={openPanel === 'dimensions'}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() => togglePanel('dimensions')}
+            >
+              {dimensionLabel}
+            </PlatformInlineOptionButton>
+            {openPanel === 'dimensions'
+              ? renderEditorPortal(
+                  <PlatformFloatingMenu
+                    className="image-canvas-editor__option-popover image-canvas-editor__portal-menu"
+                    label={`${isRedraw ? '重绘' : '快速编辑'}尺寸选项`}
+                    placement="top-start"
+                    style={buildPortalMenuStyle(
+                      dimensionsButtonRef.current,
+                      'above',
+                    )}
+                    onPointerDown={(event) => event.stopPropagation()}
+                  >
+                    <div className="image-canvas-editor__option-popover-sections">
+                      <div className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          比例
+                        </span>
+                        <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--card">
+                          {dimensionOptions.aspectRatios.map((aspectRatio) => (
+                            <QuickEditOptionChoice
+                              key={aspectRatio}
+                              selected={selectedAspectRatio === aspectRatio}
+                              className="image-canvas-editor__option-popover-choice--ratio"
+                              ariaLabel={`比例 ${aspectRatio}`}
+                              onClick={() => updatePanel({ aspectRatio })}
+                            >
+                              <span
+                                className="image-canvas-editor__ratio-wireframe"
+                                data-ratio={aspectRatio}
+                                aria-hidden="true"
+                              />
+                              <span>{aspectRatio}</span>
+                            </QuickEditOptionChoice>
+                          ))}
+                        </div>
+                      </div>
+                      <div className="image-canvas-editor__option-popover-section">
+                        <span className="image-canvas-editor__option-popover-title">
+                          尺寸
+                        </span>
+                        <div className="image-canvas-editor__option-popover-items">
+                          {dimensionOptions.imageSizes.map((imageSize) => (
+                            <QuickEditOptionChoice
+                              key={imageSize}
+                              selected={selectedImageSize === imageSize}
+                              ariaLabel={`尺寸 ${imageSize}`}
+                              onClick={() => updatePanel({ imageSize })}
+                            >
+                              {imageSize}
+                            </QuickEditOptionChoice>
+                          ))}
+                        </div>
+                      </div>
+                    </div>
+                  </PlatformFloatingMenu>,
+                )
+              : null}
+          </div>
+          <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--model">
+            <PlatformInlineOptionButton
+              ref={modelButtonRef}
+              className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--model"
+              aria-label={`${isRedraw ? '重绘' : '快速编辑'}模型 ${selectedModelLabel}`}
+              aria-expanded={openPanel === 'model'}
+              disabled={isGenerating}
+              trailingIcon={<ChevronDown className="h-3 w-3" />}
+              onClick={() => togglePanel('model')}
+            >
+              <span className="image-canvas-editor__model-trigger-label">
+                <span
+                  className="image-canvas-editor__model-icon"
+                  aria-hidden="true"
+                >
+                  <Cpu />
+                </span>
+                <span>{selectedModelLabel}</span>
+              </span>
+            </PlatformInlineOptionButton>
+            {openPanel === 'model'
+              ? renderEditorPortal(
+                  <PlatformFloatingMenu
+                    className="image-canvas-editor__option-popover image-canvas-editor__option-popover--model image-canvas-editor__portal-menu"
+                    label={`${isRedraw ? '重绘' : '快速编辑'}模型选项`}
+                    placement="top-start"
+                    style={buildPortalMenuStyle(modelButtonRef.current, 'above')}
+                    onPointerDown={(event) => event.stopPropagation()}
+                  >
+                    <div className="image-canvas-editor__option-popover-items image-canvas-editor__option-popover-items--model">
+                      {EDITOR_IMAGE_MODEL_OPTIONS.map((option) => {
+                        const selected = selectedModel === option.value;
+                        return (
+                          <QuickEditOptionChoice
+                            key={option.value}
+                            selected={selected}
+                            className="image-canvas-editor__option-popover-choice--model"
+                            onClick={() => updateModel(option.value)}
+                          >
+                            <span
+                              className="image-canvas-editor__model-icon"
+                              aria-hidden="true"
+                            >
+                              <Cpu />
+                            </span>
+                            <span>{option.label}</span>
+                            <Check
+                              className="image-canvas-editor__option-selected-check"
+                              data-visible={selected}
+                              aria-hidden="true"
+                            />
+                          </QuickEditOptionChoice>
+                        );
+                      })}
+                    </div>
+                  </PlatformFloatingMenu>,
+                )
+              : null}
+          </div>
+          <PlatformActionButton
+            type="submit"
+            tone="secondary"
+            size="xs"
+            shape="pill"
+            className="image-canvas-editor__generation-submit image-canvas-editor__quick-edit-submit"
+            disabled={isGenerating}
+            aria-label={isGenerating ? '生成中' : '生成'}
+          >
+            {isGenerating ? (
+              '生成中'
+            ) : (
+              <>
+                <span>生成</span>
+                <span className="image-canvas-editor__mud-point-inline">
+                  {calculateEditorImageModelPrice(panel.model)}泥点
+                </span>
+              </>
+            )}
+          </PlatformActionButton>
+        </div>
+      </form>
+      {!isRedraw && isReferenceMenuOpen && referenceButtonRef
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu"
+              label="快速编辑参考图来源"
+              placement="top-start"
+              style={buildPortalMenuStyle(referenceButtonRef.current, 'above')}
+            >
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsReferenceMenuOpen?.(false);
+                  setIsPickingQuickEditReferenceFromCanvas?.(true);
+                }}
+              >
+                从画布中选择
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsReferenceMenuOpen?.(false);
+                  setIsPickingQuickEditReferenceFromCanvas?.(false);
+                  onRequestUpload('quick-edit-reference');
+                }}
+              >
+                上传图片
+              </PlatformFloatingMenuItem>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasRasterEditModel.test.ts b/src/components/image-editor/ImageCanvasRasterEditModel.test.ts
new file mode 100644
index 000000000..6c541c5d1
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasRasterEditModel.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildCropExpandInsetsFromFrame,
+  buildCropExpandGeometry,
+  buildCropExpandLayerPatch,
+  parseCropExpandInsetValue,
+} from './ImageCanvasRasterEditModel';
+
+describe('ImageCanvasRasterEditModel', () => {
+  it('builds transparent expansion geometry around the source image', () => {
+    expect(
+      buildCropExpandGeometry({
+        width: 100,
+        height: 80,
+        insets: { left: 10, top: 6, right: 12, bottom: 8 },
+      }),
+    ).toEqual({
+      outputWidth: 122,
+      outputHeight: 94,
+      sourceX: 0,
+      sourceY: 0,
+      sourceWidth: 100,
+      sourceHeight: 80,
+      targetX: 10,
+      targetY: 6,
+    });
+  });
+
+  it('builds crop geometry and moves the layer origin to the cropped bounds', () => {
+    const insets = { left: -10, top: -6, right: -12, bottom: -8 };
+    expect(
+      buildCropExpandGeometry({
+        width: 100,
+        height: 80,
+        insets,
+      }),
+    ).toMatchObject({
+      outputWidth: 78,
+      outputHeight: 66,
+      sourceX: 10,
+      sourceY: 6,
+      sourceWidth: 78,
+      sourceHeight: 66,
+      targetX: 0,
+      targetY: 0,
+    });
+    expect(
+      buildCropExpandLayerPatch({
+        layerX: 50,
+        layerY: 40,
+        insets,
+        outputWidth: 78,
+        outputHeight: 66,
+      }),
+    ).toEqual({
+      x: 60,
+      y: 46,
+      width: 78,
+      height: 66,
+      originalWidth: 78,
+      originalHeight: 66,
+    });
+  });
+
+  it('parses integer crop-expand values and rejects invalid input', () => {
+    expect(parseCropExpandInsetValue(' 12 ')).toBe(12);
+    expect(parseCropExpandInsetValue('')).toBe(0);
+    expect(() => parseCropExpandInsetValue('左')).toThrow('裁扩数值必须是整数');
+  });
+
+  it('converts a dragged canvas frame into transparent crop-expand insets', () => {
+    expect(
+      buildCropExpandInsetsFromFrame({
+        layer: {
+          x: 100,
+          y: 80,
+          width: 200,
+          height: 120,
+          originalWidth: 400,
+          originalHeight: 240,
+        },
+        frame: {
+          x: 90,
+          y: 90,
+          width: 240,
+          height: 90,
+        },
+      }),
+    ).toEqual({
+      left: 20,
+      top: -20,
+      right: 60,
+      bottom: -40,
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasRasterEditModel.ts b/src/components/image-editor/ImageCanvasRasterEditModel.ts
new file mode 100644
index 000000000..3b5f328c0
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasRasterEditModel.ts
@@ -0,0 +1,225 @@
+import { removeBackgroundFromRgba } from '../../../packages/shared/src/assets/chromaKey';
+
+export type CropExpandInsets = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+};
+
+export type CropExpandGeometry = {
+  outputWidth: number;
+  outputHeight: number;
+  sourceX: number;
+  sourceY: number;
+  sourceWidth: number;
+  sourceHeight: number;
+  targetX: number;
+  targetY: number;
+};
+
+export type CropExpandFrame = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type RasterEditResult = {
+  imageSrc: string;
+  width: number;
+  height: number;
+};
+
+function assertCanvasSupport() {
+  if (typeof document === 'undefined') {
+    throw new Error('当前环境不支持图片编辑');
+  }
+}
+
+function loadImageElement(source: string) {
+  return new Promise<HTMLImageElement>((resolve, reject) => {
+    const image = new Image();
+    image.crossOrigin = 'anonymous';
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new Error('图片读取失败'));
+    image.src = source;
+  });
+}
+
+function createRasterCanvas(width: number, height: number) {
+  assertCanvasSupport();
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d', { willReadFrequently: true });
+  if (!context) {
+    throw new Error('当前浏览器不支持图片编辑');
+  }
+  return { canvas, context };
+}
+
+function resolveImageSize(image: HTMLImageElement) {
+  return {
+    width: Math.max(1, image.naturalWidth || image.width || 1),
+    height: Math.max(1, image.naturalHeight || image.height || 1),
+  };
+}
+
+export function parseCropExpandInsetValue(value: string) {
+  const trimmedValue = value.trim();
+  if (!trimmedValue) {
+    return 0;
+  }
+  const parsedValue = Number.parseInt(trimmedValue, 10);
+  if (!Number.isFinite(parsedValue)) {
+    throw new Error('裁扩数值必须是整数');
+  }
+  return parsedValue;
+}
+
+export function buildCropExpandInsetsFromFrame({
+  layer,
+  frame,
+}: {
+  layer: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+  };
+  frame: CropExpandFrame;
+}): CropExpandInsets {
+  const scaleX =
+    layer.width > 0 ? Math.max(1, layer.originalWidth) / layer.width : 1;
+  const scaleY =
+    layer.height > 0 ? Math.max(1, layer.originalHeight) / layer.height : 1;
+  const sourceRight = layer.x + layer.width;
+  const sourceBottom = layer.y + layer.height;
+  const frameRight = frame.x + frame.width;
+  const frameBottom = frame.y + frame.height;
+
+  return {
+    left: Math.round((layer.x - frame.x) * scaleX),
+    top: Math.round((layer.y - frame.y) * scaleY),
+    right: Math.round((frameRight - sourceRight) * scaleX),
+    bottom: Math.round((frameBottom - sourceBottom) * scaleY),
+  };
+}
+
+export function buildCropExpandGeometry({
+  width,
+  height,
+  insets,
+}: {
+  width: number;
+  height: number;
+  insets: CropExpandInsets;
+}): CropExpandGeometry {
+  const sourceWidth = Math.max(1, Math.round(width || 1));
+  const sourceHeight = Math.max(1, Math.round(height || 1));
+  const cropLeft = Math.max(0, -insets.left);
+  const cropTop = Math.max(0, -insets.top);
+  const cropRight = Math.max(0, -insets.right);
+  const cropBottom = Math.max(0, -insets.bottom);
+  const targetX = Math.max(0, insets.left);
+  const targetY = Math.max(0, insets.top);
+  const drawableWidth = sourceWidth - cropLeft - cropRight;
+  const drawableHeight = sourceHeight - cropTop - cropBottom;
+  if (drawableWidth <= 0 || drawableHeight <= 0) {
+    throw new Error('裁剪范围不能小于 1 像素');
+  }
+
+  return {
+    outputWidth: targetX + drawableWidth + Math.max(0, insets.right),
+    outputHeight: targetY + drawableHeight + Math.max(0, insets.bottom),
+    sourceX: cropLeft,
+    sourceY: cropTop,
+    sourceWidth: drawableWidth,
+    sourceHeight: drawableHeight,
+    targetX,
+    targetY,
+  };
+}
+
+export function buildCropExpandLayerPatch({
+  layerX,
+  layerY,
+  insets,
+  outputWidth,
+  outputHeight,
+}: {
+  layerX: number;
+  layerY: number;
+  insets: CropExpandInsets;
+  outputWidth: number;
+  outputHeight: number;
+}) {
+  return {
+    x: layerX - insets.left,
+    y: layerY - insets.top,
+    width: outputWidth,
+    height: outputHeight,
+    originalWidth: outputWidth,
+    originalHeight: outputHeight,
+  };
+}
+
+export async function renderCropExpandImage({
+  source,
+  insets,
+}: {
+  source: string;
+  insets: CropExpandInsets;
+}): Promise<RasterEditResult> {
+  const image = await loadImageElement(source);
+  const imageSize = resolveImageSize(image);
+  const geometry = buildCropExpandGeometry({
+    width: imageSize.width,
+    height: imageSize.height,
+    insets,
+  });
+  const { canvas, context } = createRasterCanvas(
+    geometry.outputWidth,
+    geometry.outputHeight,
+  );
+  // 中文注释：画布默认透明，扩大出来的新区域不填色，直接保留 alpha=0。
+  context.clearRect(0, 0, geometry.outputWidth, geometry.outputHeight);
+  context.drawImage(
+    image,
+    geometry.sourceX,
+    geometry.sourceY,
+    geometry.sourceWidth,
+    geometry.sourceHeight,
+    geometry.targetX,
+    geometry.targetY,
+    geometry.sourceWidth,
+    geometry.sourceHeight,
+  );
+
+  return {
+    imageSrc: canvas.toDataURL('image/png'),
+    width: geometry.outputWidth,
+    height: geometry.outputHeight,
+  };
+}
+
+export async function removeImageBackground(
+  source: string,
+): Promise<RasterEditResult> {
+  const image = await loadImageElement(source);
+  const { width, height } = resolveImageSize(image);
+  const { canvas, context } = createRasterCanvas(width, height);
+  context.drawImage(image, 0, 0, width, height);
+  const imageData = context.getImageData(0, 0, width, height);
+  removeBackgroundFromRgba(imageData.data, width, height);
+
+  context.putImageData(imageData, 0, 0);
+  return {
+    imageSrc: canvas.toDataURL('image/png'),
+    width,
+    height,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasReferenceSlot.tsx b/src/components/image-editor/ImageCanvasReferenceSlot.tsx
new file mode 100644
index 000000000..79e41ff8f
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasReferenceSlot.tsx
@@ -0,0 +1,116 @@
+import { type ReactNode, type RefObject } from 'react';
+import { X } from 'lucide-react';
+
+type ImageCanvasReferenceSlotTone =
+  | 'default'
+  | 'spec'
+  | 'icon'
+  | 'ui'
+  | 'character'
+  | 'quick-edit'
+  | 'video'
+  | 'audio';
+
+type ImageCanvasReferenceSlotProps = {
+  buttonRef?: RefObject<HTMLButtonElement | null>;
+  tone?: ImageCanvasReferenceSlotTone;
+  className?: string;
+  icon: ReactNode;
+  label: string;
+  ariaLabel: string;
+  title?: string;
+  imageSrc?: string | null;
+  disabled?: boolean;
+  isAdd?: boolean;
+  onClick?: () => void;
+  onRemove?: () => void;
+  removeLabel?: string;
+};
+
+export function ImageCanvasReferenceSlot({
+  buttonRef,
+  tone = 'default',
+  className,
+  icon,
+  label,
+  ariaLabel,
+  title,
+  imageSrc,
+  disabled = false,
+  isAdd = false,
+  onClick,
+  onRemove,
+  removeLabel,
+}: ImageCanvasReferenceSlotProps) {
+  const hasPreviewImage = Boolean(imageSrc);
+  const slotClassName = [
+    'image-canvas-editor__reference-chip',
+    `image-canvas-editor__reference-chip--${tone}`,
+    hasPreviewImage
+      ? 'image-canvas-editor__reference-chip--has-image'
+      : 'image-canvas-editor__reference-chip--icon-only',
+    isAdd ? 'image-canvas-editor__reference-chip--upload' : null,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const slotContent = (
+    <>
+      <span className="image-canvas-editor__reference-chip-icon">
+        {hasPreviewImage ? (
+          <img src={imageSrc ?? undefined} alt="" aria-hidden="true" />
+        ) : (
+          icon
+        )}
+      </span>
+      <span className="image-canvas-editor__reference-chip-label">{label}</span>
+      {title && title !== label ? (
+        <span className="image-canvas-editor__reference-chip-source-label">
+          {title}
+        </span>
+      ) : null}
+    </>
+  );
+  return (
+    <span className="image-canvas-editor__reference-slot">
+      {onClick || buttonRef ? (
+        <button
+          ref={buttonRef}
+          type="button"
+          className={slotClassName}
+          disabled={disabled}
+          aria-label={ariaLabel}
+          title={title ?? ariaLabel}
+          onClick={onClick}
+        >
+          {slotContent}
+        </button>
+      ) : (
+        <span
+          className={slotClassName}
+          aria-label={ariaLabel}
+          title={title ?? ariaLabel}
+        >
+          {slotContent}
+        </span>
+      )}
+      {onRemove ? (
+        <button
+          type="button"
+          className="image-canvas-editor__reference-chip-remove"
+          disabled={disabled}
+          aria-label={removeLabel ?? `删除${ariaLabel}`}
+          title="删除"
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            onRemove();
+          }}
+        >
+          <X className="h-3 w-3" aria-hidden="true" />
+        </button>
+      ) : null}
+    </span>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx
new file mode 100644
index 000000000..d2f843139
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.test.tsx
@@ -0,0 +1,211 @@
+/* @vitest-environment jsdom */
+
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  within,
+} from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { ImageCanvasSelectedLayerToolbarView } from './ImageCanvasSelectedLayerToolbarView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '生成主图',
+    src: 'data:image/png;base64,layer',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function renderSelectedToolbar(
+  overrides: Partial<Parameters<typeof ImageCanvasSelectedLayerToolbarView>[0]> = {},
+) {
+  const props: Parameters<typeof ImageCanvasSelectedLayerToolbarView>[0] = {
+    selectedLayer: createLayer(),
+    selectedToolbarStyle: { left: 12, top: 24 },
+    onOpenQuickEditPanel: vi.fn(),
+    onOpenRedrawPanel: vi.fn(),
+    onOpenCropExpandPanel: vi.fn(),
+    onRemoveBackground: vi.fn(),
+    onExtractUiDesignAssets: vi.fn(),
+    onOpenCharacterAnimationPanel: vi.fn(),
+    onDownloadLayer: vi.fn(),
+    ...overrides,
+  };
+
+  render(<ImageCanvasSelectedLayerToolbarView {...props} />);
+
+  return props;
+}
+
+describe('ImageCanvasSelectedLayerToolbarView', () => {
+  it('renders common layer actions in the Lovart toolbar order and forwards callbacks', () => {
+    const props = renderSelectedToolbar();
+    const toolbar = screen.getByRole('toolbar', { name: '图片工具栏' });
+    const buttons = within(toolbar).getAllByRole('button');
+
+    expect(buttons.map((button) => button.getAttribute('aria-label'))).toEqual([
+      '快速编辑',
+      '裁扩按钮',
+      '去除背景按钮',
+      '改造',
+      '下载按钮',
+    ]);
+
+    fireEvent.click(within(toolbar).getByRole('button', { name: '快速编辑' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '裁扩按钮' }));
+    fireEvent.click(
+      within(toolbar).getByRole('button', { name: '去除背景按钮' }),
+    );
+    fireEvent.click(within(toolbar).getByRole('button', { name: '改造' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '下载按钮' }));
+
+    expect(props.onOpenQuickEditPanel).toHaveBeenCalledWith(props.selectedLayer);
+    expect(props.onOpenCropExpandPanel).toHaveBeenCalledWith(
+      props.selectedLayer,
+    );
+    expect(props.onRemoveBackground).toHaveBeenCalledWith(props.selectedLayer);
+    expect(props.onOpenRedrawPanel).toHaveBeenCalledWith(props.selectedLayer);
+    expect(props.onDownloadLayer).toHaveBeenCalledWith(props.selectedLayer);
+    expect(
+      within(toolbar).queryByRole('button', { name: '删除图片' }),
+    ).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: '修改图片' }),
+    ).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: /查看.*图片信息/u }),
+    ).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: '提取素材' }),
+    ).toBeNull();
+    expect(
+      within(toolbar)
+        .getByRole('button', { name: '去除背景按钮' })
+        .querySelector('.lucide-image-off'),
+    ).toBeTruthy();
+  });
+
+  it('renders UI design asset extraction after remove background', () => {
+    const layer = createLayer({
+      sourceType: 'generated',
+      assetKind: 'ui-design',
+    });
+    const props = renderSelectedToolbar({ selectedLayer: layer });
+    const toolbar = screen.getByRole('toolbar', { name: '图片工具栏' });
+    const buttons = within(toolbar).getAllByRole('button');
+
+    expect(buttons.map((button) => button.getAttribute('aria-label'))).toEqual([
+      '快速编辑',
+      '裁扩按钮',
+      '去除背景按钮',
+      '提取素材',
+      '改造',
+      '下载按钮',
+    ]);
+
+    fireEvent.click(within(toolbar).getByRole('button', { name: '提取素材' }));
+
+    expect(props.onExtractUiDesignAssets).toHaveBeenCalledWith(layer);
+  });
+
+  it('keeps only remodel and download for audio layers', () => {
+    const layer = createLayer({
+      title: '游戏音效',
+      src: 'data:audio/mpeg;base64,audio',
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+    });
+    const props = renderSelectedToolbar({ selectedLayer: layer });
+    const toolbar = screen.getByRole('toolbar', { name: '素材工具栏' });
+    const buttons = within(toolbar).getAllByRole('button');
+
+    expect(buttons.map((button) => button.getAttribute('aria-label'))).toEqual([
+      '改造',
+      '下载按钮',
+    ]);
+    expect(within(toolbar).queryByRole('button', { name: '快速编辑' })).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: '裁扩按钮' }),
+    ).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: '去除背景按钮' }),
+    ).toBeNull();
+    expect(
+      within(toolbar).queryByRole('button', { name: '生成动画' }),
+    ).toBeNull();
+
+    fireEvent.click(within(toolbar).getByRole('button', { name: '改造' }));
+    fireEvent.click(within(toolbar).getByRole('button', { name: '下载按钮' }));
+
+    expect(props.onOpenRedrawPanel).toHaveBeenCalledWith(layer);
+    expect(props.onDownloadLayer).toHaveBeenCalledWith(layer);
+  });
+
+  it('renders character animation only for character layers', () => {
+    const layer = createLayer({
+      sourceType: 'generated',
+      assetKind: 'character',
+    });
+    const props = renderSelectedToolbar({ selectedLayer: layer });
+    const animationButton = screen.getByRole('button', { name: '生成动画' });
+
+    expect(animationButton.textContent).toContain('生成动画');
+    expect(animationButton.querySelector('.lucide-person-standing')).toBeTruthy();
+
+    fireEvent.click(animationButton);
+
+    expect(props.onOpenCharacterAnimationPanel).toHaveBeenCalledWith(layer);
+
+    cleanup();
+    renderSelectedToolbar({ selectedLayer: createLayer({ id: 'layer-2' }) });
+    expect(screen.queryByRole('button', { name: '生成动画' })).toBeNull();
+  });
+
+  it('renders nothing without a selected layer or toolbar position', () => {
+    const { rerender } = render(
+      <ImageCanvasSelectedLayerToolbarView
+        selectedLayer={null}
+        selectedToolbarStyle={{ left: 0, top: 0 }}
+        onOpenQuickEditPanel={vi.fn()}
+        onOpenRedrawPanel={vi.fn()}
+        onOpenCropExpandPanel={vi.fn()}
+        onRemoveBackground={vi.fn()}
+        onExtractUiDesignAssets={vi.fn()}
+        onOpenCharacterAnimationPanel={vi.fn()}
+        onDownloadLayer={vi.fn()}
+      />,
+    );
+
+    expect(screen.queryByRole('toolbar', { name: '图片工具栏' })).toBeNull();
+
+    rerender(
+      <ImageCanvasSelectedLayerToolbarView
+        selectedLayer={createLayer()}
+        selectedToolbarStyle={null}
+        onOpenQuickEditPanel={vi.fn()}
+        onOpenRedrawPanel={vi.fn()}
+        onOpenCropExpandPanel={vi.fn()}
+        onRemoveBackground={vi.fn()}
+        onExtractUiDesignAssets={vi.fn()}
+        onOpenCharacterAnimationPanel={vi.fn()}
+        onDownloadLayer={vi.fn()}
+      />,
+    );
+
+    expect(screen.queryByRole('toolbar', { name: '图片工具栏' })).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx
new file mode 100644
index 000000000..c7f22d13a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSelectedLayerToolbarView.tsx
@@ -0,0 +1,147 @@
+import {
+  Crop,
+  Download,
+  ImageOff,
+  PersonStanding,
+  Scissors,
+  Sparkles,
+  WandSparkles,
+} from 'lucide-react';
+import type { CSSProperties } from 'react';
+
+import { PlatformIconButton } from '../common/PlatformIconButton';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+
+type ImageCanvasSelectedLayerToolbarViewProps = {
+  selectedLayer: CanvasLayer | null;
+  selectedToolbarStyle: CSSProperties | null;
+  onOpenQuickEditPanel: (layer: CanvasLayer) => void;
+  onOpenRedrawPanel: (layer: CanvasLayer) => void;
+  onOpenCropExpandPanel: (layer: CanvasLayer) => void;
+  onRemoveBackground: (layer: CanvasLayer) => void;
+  onExtractUiDesignAssets: (layer: CanvasLayer) => void;
+  onOpenCharacterAnimationPanel: (layer: CanvasLayer) => void;
+  onDownloadLayer: (layer: CanvasLayer) => void;
+};
+
+export function ImageCanvasSelectedLayerToolbarView({
+  selectedLayer,
+  selectedToolbarStyle,
+  onOpenQuickEditPanel,
+  onOpenRedrawPanel,
+  onOpenCropExpandPanel,
+  onRemoveBackground,
+  onExtractUiDesignAssets,
+  onOpenCharacterAnimationPanel,
+  onDownloadLayer,
+}: ImageCanvasSelectedLayerToolbarViewProps) {
+  if (!selectedLayer || !selectedToolbarStyle) {
+    return null;
+  }
+
+  if (selectedLayer.mediaType === 'audio') {
+    return (
+      <div
+        className="image-canvas-editor__floating-toolbar"
+        style={selectedToolbarStyle}
+        role="toolbar"
+        aria-label="素材工具栏"
+        onPointerDown={(event) => event.stopPropagation()}
+      >
+        <PlatformIconButton
+          className="image-canvas-editor__floating-toolbar-text-button"
+          label="改造"
+          title="改造"
+          icon={<WandSparkles className="h-4 w-4" />}
+          onClick={() => onOpenRedrawPanel(selectedLayer)}
+        >
+          <span>改造</span>
+        </PlatformIconButton>
+        <EditorIconButton
+          label="下载按钮"
+          title="下载按钮"
+          icon={Download}
+          onClick={() => onDownloadLayer(selectedLayer)}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="image-canvas-editor__floating-toolbar"
+      style={selectedToolbarStyle}
+      role="toolbar"
+      aria-label="图片工具栏"
+      onPointerDown={(event) => event.stopPropagation()}
+    >
+      <PlatformIconButton
+        className="image-canvas-editor__floating-toolbar-text-button"
+        label="快速编辑"
+        title="快速编辑"
+        icon={<Sparkles className="h-4 w-4" />}
+        onClick={() => onOpenQuickEditPanel(selectedLayer)}
+      >
+        <span>快速编辑</span>
+      </PlatformIconButton>
+      <span
+        aria-hidden="true"
+        className="image-canvas-editor__floating-toolbar-divider"
+      />
+      <EditorIconButton
+        label="裁扩按钮"
+        title="裁扩按钮"
+        icon={Crop}
+        onClick={() => onOpenCropExpandPanel(selectedLayer)}
+      />
+      <EditorIconButton
+        label="去除背景按钮"
+        title="去除背景按钮"
+        icon={ImageOff}
+        onClick={() => onRemoveBackground(selectedLayer)}
+      />
+      {selectedLayer.assetKind === 'ui-design' ? (
+        <PlatformIconButton
+          className="image-canvas-editor__floating-toolbar-text-button"
+          label="提取素材"
+          title="提取素材"
+          icon={<Scissors className="h-4 w-4" />}
+          onClick={() => onExtractUiDesignAssets(selectedLayer)}
+        >
+          <span>提取素材</span>
+        </PlatformIconButton>
+      ) : null}
+      {selectedLayer.assetKind === 'character' ? (
+        <PlatformIconButton
+          className="image-canvas-editor__floating-toolbar-text-button"
+          label="生成动画"
+          title="生成动画"
+          icon={<PersonStanding className="h-4 w-4" />}
+          onClick={() => onOpenCharacterAnimationPanel(selectedLayer)}
+        >
+          <span>生成动画</span>
+        </PlatformIconButton>
+      ) : null}
+      <span
+        aria-hidden="true"
+        className="image-canvas-editor__floating-toolbar-divider"
+      />
+      <PlatformIconButton
+        className="image-canvas-editor__floating-toolbar-text-button"
+        label="改造"
+        title="改造"
+        icon={<WandSparkles className="h-4 w-4" />}
+        onClick={() => onOpenRedrawPanel(selectedLayer)}
+      >
+        <span>改造</span>
+      </PlatformIconButton>
+      <EditorIconButton
+        label="下载按钮"
+        title="下载按钮"
+        icon={Download}
+        onClick={() => onDownloadLayer(selectedLayer)}
+      />
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasSelectionModel.ts b/src/components/image-editor/ImageCanvasSelectionModel.ts
new file mode 100644
index 000000000..df1151e7a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSelectionModel.ts
@@ -0,0 +1,84 @@
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+
+export const CANVAS_GENERATION_SELECTION_PREFIX = 'generation-dialog:';
+
+export function getCanvasGenerationSelectionId(dialogId: string) {
+  return `${CANVAS_GENERATION_SELECTION_PREFIX}${dialogId}`;
+}
+
+export function getCanvasGenerationDialogIdFromSelectionId(targetId: string) {
+  return targetId.startsWith(CANVAS_GENERATION_SELECTION_PREFIX)
+    ? targetId.slice(CANVAS_GENERATION_SELECTION_PREFIX.length)
+    : null;
+}
+
+export function isCanvasGenerationSelectionId(targetId: string) {
+  return getCanvasGenerationDialogIdFromSelectionId(targetId) !== null;
+}
+
+export function getSelectedLayerIds(selectionIds: string[]) {
+  return selectionIds.filter(
+    (selectionId) => !isCanvasGenerationSelectionId(selectionId),
+  );
+}
+
+export function getSelectedGenerationDialogIds(selectionIds: string[]) {
+  return selectionIds.flatMap((selectionId) => {
+    const dialogId = getCanvasGenerationDialogIdFromSelectionId(selectionId);
+    return dialogId ? [dialogId] : [];
+  });
+}
+
+export function dedupeSelectionIds(selectionIds: string[]) {
+  return Array.from(new Set(selectionIds));
+}
+
+export function firstSelectedLayerId(selectionIds: string[]) {
+  return getSelectedLayerIds(selectionIds)[0] ?? null;
+}
+
+export function normalizeCanvasSelectionIds({
+  selectionIds,
+  layers,
+  generationDialogs,
+}: {
+  selectionIds: string[];
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+}) {
+  const layerIds = new Set(layers.map((layer) => layer.id));
+  const generationDialogIds = new Set(
+    generationDialogs.map((dialog) => dialog.id),
+  );
+  return dedupeSelectionIds(selectionIds).filter((selectionId) => {
+    if (isCanvasGenerationSelectionId(selectionId)) {
+      const dialogId = getCanvasGenerationDialogIdFromSelectionId(selectionId);
+      return Boolean(dialogId && generationDialogIds.has(dialogId));
+    }
+    return layerIds.has(selectionId);
+  });
+}
+
+export function resolvePointerSelection({
+  targetId,
+  selectedIds,
+  isMultiSelectGesture,
+}: {
+  targetId: string;
+  selectedIds: string[];
+  isMultiSelectGesture: boolean;
+}) {
+  if (!isMultiSelectGesture) {
+    return [targetId];
+  }
+  if (!selectedIds.includes(targetId)) {
+    return [...selectedIds, targetId];
+  }
+  if (selectedIds.length <= 1) {
+    return [targetId];
+  }
+  return selectedIds.filter((selectedId) => selectedId !== targetId);
+}
diff --git a/src/components/image-editor/ImageCanvasSidebarView.test.tsx b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
new file mode 100644
index 000000000..b8d597fc5
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSidebarView.test.tsx
@@ -0,0 +1,275 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { createRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ImageCanvasPanelDockView } from './ImageCanvasPanelDockView';
+import {
+  ImageCanvasSidebarView,
+  type ImageCanvasSidebarViewProps,
+} from './ImageCanvasSidebarView';
+import type {
+  CanvasLayer,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
+
+function createAsset(overrides: Partial<EditorAsset> = {}): EditorAsset {
+  return {
+    id: 'asset-1',
+    label: '账号素材A',
+    src: '/creation-type-references/puzzle.webp',
+    width: 640,
+    height: 640,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function createFolder(
+  overrides: Partial<EditorAssetFolder> = {},
+): EditorAssetFolder {
+  return {
+    id: 'project',
+    label: '项目素材',
+    collapsed: false,
+    systemDefault: true,
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '图层A',
+    src: '/creation-type-references/puzzle.webp',
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createSidebarProps(
+  overrides: Partial<ImageCanvasSidebarViewProps> = {},
+): ImageCanvasSidebarViewProps {
+  const folder = createFolder();
+  const asset = createAsset();
+
+  return {
+    activeSidebarPanel: 'assets',
+    assetListRef: createRef<HTMLDivElement>(),
+    assetPointerDragRef: { current: null },
+    suppressAssetClickRef: { current: false },
+    assets: [asset],
+    groupedAssets: [{ ...folder, assets: [asset] }],
+    assetFolders: [folder],
+    layers: [createLayer()],
+    selectedLayerId: null,
+    selectedLayerIds: [],
+    isAssetSelectionMode: false,
+    selectedAssetIds: new Set(),
+    assetMoveDropFolderId: null,
+    pinnedAssetMoveFolderId: null,
+    creatingFolder: false,
+    newFolderName: '',
+    renamingFolder: null,
+    renamingAsset: null,
+    allSelectableAssetsSelected: false,
+    assetMarquee: null,
+    setIsAssetSelectionMode: vi.fn(),
+    setCreatingFolder: vi.fn(),
+    setNewFolderName: vi.fn(),
+    setRenamingFolder: vi.fn(),
+    setRenamingAsset: vi.fn(),
+    setActiveUploadFolderId: vi.fn(),
+    setUploadDropTarget: vi.fn(),
+    setAssetPointerDrag: vi.fn(),
+    setSelectedAssetIds: vi.fn(),
+    setImageContextMenu: vi.fn(),
+    setContextMenu: vi.fn(),
+    onAssetMarqueePointerDown: vi.fn(),
+    onAssetMarqueePointerMove: vi.fn(),
+    onAssetMarqueePointerUp: vi.fn(),
+    updateAssetMoveDropFolder: vi.fn(),
+    addUploadedFiles: vi.fn(),
+    requestUpload: vi.fn(),
+    moveAssetToFolder: vi.fn(),
+    commitNewAssetFolder: vi.fn(),
+    toggleAssetFolder: vi.fn(),
+    startRenamingFolder: vi.fn(),
+    commitFolderRename: vi.fn(),
+    deleteAssetFolder: vi.fn(),
+    startRenamingAsset: vi.fn(),
+    commitAssetRename: vi.fn(),
+    deleteUploadedAsset: vi.fn(),
+    toggleAssetSelected: vi.fn(),
+    addAssetLayer: vi.fn(),
+    toggleAllAssetsSelected: vi.fn(),
+    deleteSelectedAssets: vi.fn(),
+    closeAssetSelectionMode: vi.fn(),
+    groupSelectedLayers: vi.fn(),
+    selectSingleLayer: vi.fn(),
+    resolveContextMenuPosition: vi.fn(() => ({ x: 0, y: 0 })),
+    getCanvasPointFromClient: vi.fn(() => ({ x: 0, y: 0 })),
+    ...overrides,
+  };
+}
+
+function SidebarTabsHarness() {
+  const chrome = useImageCanvasEditorChrome({ openEditorLoginModal: vi.fn() });
+  const asset = createAsset();
+  const folder = createFolder();
+  const layer = createLayer({ title: '图层B', zIndex: 2 });
+  const sidebarProps = createSidebarProps({
+    activeSidebarPanel: chrome.activeSidebarPanel,
+    assets: [asset],
+    groupedAssets: [{ ...folder, assets: [asset] }],
+    assetFolders: [folder],
+    layers: [layer],
+    selectedLayerId: null,
+    selectedLayerIds: [],
+  });
+
+  return (
+    <div>
+      <ImageCanvasSidebarView {...sidebarProps} />
+      <ImageCanvasPanelDockView
+        viewport={{ x: 0, y: 0, scale: 1 }}
+        canvasBackgroundColor={chrome.canvasBackgroundColor}
+        canvasBackgroundHexValue={chrome.canvasBackgroundHexValue}
+        canUndo={false}
+        canRedo={false}
+        isZoomMenuOpen={false}
+        isBackgroundSettingsOpen={false}
+        activeSidebarPanel={chrome.activeSidebarPanel}
+        isMinimapOpen={false}
+        minimapModel={null}
+        onFitLayers={vi.fn()}
+        onUndoCanvasChange={vi.fn()}
+        onRedoCanvasChange={vi.fn()}
+        onUpdateScaleFromCenter={vi.fn()}
+        onToggleZoomMenu={vi.fn()}
+        onCloseZoomMenu={vi.fn()}
+        onToggleBackgroundSettings={vi.fn()}
+        onApplyCanvasBackgroundColor={vi.fn()}
+        onCanvasBackgroundHexChange={vi.fn()}
+        onToggleSidebarPanel={chrome.toggleSidebarPanel}
+        onToggleMinimap={vi.fn()}
+        onMinimapPointerDown={vi.fn()}
+      />
+    </div>
+  );
+}
+
+describe('ImageCanvasSidebarView', () => {
+  it('renders the asset library folders and asset actions', () => {
+    render(<ImageCanvasSidebarView {...createSidebarProps()} />);
+
+    const sidebar = screen.getByRole('complementary', { name: '图片资源栏' });
+    const folder = within(sidebar).getByRole('region', { name: '项目素材' });
+
+    expect(within(sidebar).getByRole('heading', { name: '素材' })).toBeTruthy();
+    expect(
+      within(folder).getByRole('button', { name: '添加账号素材A' }),
+    ).toBeTruthy();
+    expect(
+      within(folder).getByRole('button', { name: '上传到项目素材' }),
+    ).toBeTruthy();
+  });
+
+  it('renders asset editing inputs with sidebar text-field chrome', () => {
+    const folder = createFolder();
+    const asset = createAsset();
+
+    render(
+      <ImageCanvasSidebarView
+        {...createSidebarProps({
+          assets: [asset],
+          groupedAssets: [{ ...folder, assets: [asset] }],
+          assetFolders: [folder],
+          creatingFolder: true,
+          newFolderName: '角色上传',
+          renamingFolder: { folderId: folder.id, value: '角色参考' },
+          renamingAsset: { assetId: asset.id, value: '主视觉素材' },
+        })}
+      />,
+    );
+
+    const folderNameInput = screen.getByLabelText('素材文件夹名称');
+    const folderRenameInput = screen.getByLabelText('重命名文件夹项目素材');
+    const assetRenameInput = screen.getByLabelText('重命名素材账号素材A');
+
+    expect(folderNameInput.className).toContain('platform-text-field');
+    expect(folderNameInput.className).toContain(
+      'image-canvas-editor__folder-create-input',
+    );
+    expect(folderRenameInput.className).toContain('platform-text-field');
+    expect(folderRenameInput.className).toContain(
+      'image-canvas-editor__folder-rename-input',
+    );
+    expect(assetRenameInput.className).toContain('platform-text-field');
+    expect(assetRenameInput.className).toContain(
+      'image-canvas-editor__asset-rename-input',
+    );
+  });
+
+  it('renders the layer panel with grouped and locked layer details', () => {
+    render(
+      <ImageCanvasSidebarView
+        {...createSidebarProps({
+          activeSidebarPanel: 'layers',
+          layers: [
+            createLayer({
+              title: '图层A',
+              groupId: 'group-1',
+              locked: true,
+              zIndex: 3,
+            }),
+          ],
+          selectedLayerId: 'layer-1',
+        })}
+      />,
+    );
+
+    const sidebar = screen.getByRole('complementary', { name: '图片资源栏' });
+
+    expect(within(sidebar).getByRole('heading', { name: '图层' })).toBeTruthy();
+    expect(
+      within(sidebar).getByRole('button', { name: '选择图层图层A' }),
+    ).toBeTruthy();
+    expect(
+      within(sidebar).getByText('320 x 240 · 已打组 · 已锁定'),
+    ).toBeTruthy();
+  });
+
+  it('keeps sidebar tab switching and repeated-click closing behavior', () => {
+    render(<SidebarTabsHarness />);
+
+    expect(screen.getByRole('heading', { name: '素材' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: '添加账号素材A' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+
+    expect(screen.getByRole('heading', { name: '图层' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: '选择图层图层B' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '打开图层' }));
+
+    expect(
+      screen.queryByRole('complementary', { name: '图片资源栏' }),
+    ).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasSidebarView.tsx b/src/components/image-editor/ImageCanvasSidebarView.tsx
new file mode 100644
index 000000000..922e7602d
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSidebarView.tsx
@@ -0,0 +1,273 @@
+import {
+  CheckSquare,
+  FolderPlus,
+  Square,
+} from 'lucide-react';
+import type {
+  Dispatch,
+  PointerEvent as ReactPointerEvent,
+  RefObject,
+  SetStateAction,
+} from 'react';
+
+import {
+  ImageCanvasAssetLibraryPanelView,
+  type GroupedEditorAssetFolder,
+  type UploadFilesOptions,
+} from './ImageCanvasAssetLibraryPanelView';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type {
+  AssetMarqueeState,
+  AssetPointerDragState,
+  CanvasContextMenuState,
+  CanvasLayer,
+  EditorAsset,
+  EditorAssetFolder,
+  ImageContextMenuState,
+  SidebarPanel,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasLayerPanelView } from './ImageCanvasLayerPanelView';
+
+export type { GroupedEditorAssetFolder, UploadFilesOptions };
+
+export type ImageCanvasSidebarViewProps = {
+  activeSidebarPanel: SidebarPanel | null;
+  assetListRef: RefObject<HTMLDivElement | null>;
+  assetPointerDragRef: { current: AssetPointerDragState | null };
+  suppressAssetClickRef: { current: boolean };
+  assets: EditorAsset[];
+  groupedAssets: GroupedEditorAssetFolder[];
+  assetFolders: EditorAssetFolder[];
+  layers: CanvasLayer[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  isAssetSelectionMode: boolean;
+  selectedAssetIds: Set<string>;
+  assetMoveDropFolderId: string | null;
+  pinnedAssetMoveFolderId: string | null;
+  creatingFolder: boolean;
+  newFolderName: string;
+  renamingFolder: { folderId: string; value: string } | null;
+  renamingAsset: { assetId: string; value: string } | null;
+  allSelectableAssetsSelected: boolean;
+  assetMarquee: AssetMarqueeState | null;
+  setIsAssetSelectionMode: Dispatch<SetStateAction<boolean>>;
+  setCreatingFolder: Dispatch<SetStateAction<boolean>>;
+  setNewFolderName: Dispatch<SetStateAction<string>>;
+  setRenamingFolder: Dispatch<
+    SetStateAction<{ folderId: string; value: string } | null>
+  >;
+  setRenamingAsset: Dispatch<
+    SetStateAction<{ assetId: string; value: string } | null>
+  >;
+  setActiveUploadFolderId: Dispatch<SetStateAction<string>>;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setSelectedAssetIds: Dispatch<SetStateAction<Set<string>>>;
+  setImageContextMenu: Dispatch<SetStateAction<ImageContextMenuState | null>>;
+  setContextMenu: Dispatch<SetStateAction<CanvasContextMenuState | null>>;
+  onAssetMarqueePointerDown: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  onAssetMarqueePointerMove: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  onAssetMarqueePointerUp: (
+    event: ReactPointerEvent<HTMLDivElement>,
+  ) => void;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  addUploadedFiles: (files: FileList | File[], options?: UploadFilesOptions) => void;
+  requestUpload: (target: UploadTarget) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  commitNewAssetFolder: () => void | Promise<void>;
+  toggleAssetFolder: (folderId: string) => void;
+  startRenamingFolder: (folder: EditorAssetFolder) => void;
+  commitFolderRename: (folder: EditorAssetFolder) => void;
+  deleteAssetFolder: (folder: EditorAssetFolder) => void;
+  startRenamingAsset: (asset: EditorAsset) => void;
+  commitAssetRename: (asset: EditorAsset) => void;
+  deleteUploadedAsset: (asset: EditorAsset) => void;
+  toggleAssetSelected: (assetId: string) => void;
+  addAssetLayer: (asset: EditorAsset) => void;
+  toggleAllAssetsSelected: () => void;
+  deleteSelectedAssets: () => void;
+  closeAssetSelectionMode: () => void;
+  groupSelectedLayers: () => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  resolveContextMenuPosition: (
+    clientX: number,
+    clientY: number,
+    menuKind: 'blank' | 'layer',
+  ) => Omit<CanvasContextMenuState, 'kind' | 'layerId' | 'canvasPoint'>;
+  getCanvasPointFromClient: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number };
+};
+
+export function ImageCanvasSidebarView({
+  activeSidebarPanel,
+  assetListRef,
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  assets,
+  groupedAssets,
+  assetFolders,
+  layers,
+  selectedLayerId,
+  selectedLayerIds,
+  isAssetSelectionMode,
+  selectedAssetIds,
+  assetMoveDropFolderId,
+  pinnedAssetMoveFolderId,
+  creatingFolder,
+  newFolderName,
+  renamingFolder,
+  renamingAsset,
+  allSelectableAssetsSelected,
+  assetMarquee,
+  setIsAssetSelectionMode,
+  setCreatingFolder,
+  setNewFolderName,
+  setRenamingFolder,
+  setRenamingAsset,
+  setActiveUploadFolderId,
+  setUploadDropTarget,
+  setAssetPointerDrag,
+  setSelectedAssetIds,
+  setImageContextMenu,
+  setContextMenu,
+  onAssetMarqueePointerDown,
+  onAssetMarqueePointerMove,
+  onAssetMarqueePointerUp,
+  updateAssetMoveDropFolder,
+  addUploadedFiles,
+  requestUpload,
+  moveAssetToFolder,
+  commitNewAssetFolder,
+  toggleAssetFolder,
+  startRenamingFolder,
+  commitFolderRename,
+  deleteAssetFolder,
+  startRenamingAsset,
+  commitAssetRename,
+  deleteUploadedAsset,
+  toggleAssetSelected,
+  addAssetLayer,
+  toggleAllAssetsSelected,
+  deleteSelectedAssets,
+  closeAssetSelectionMode,
+  groupSelectedLayers,
+  selectSingleLayer,
+  resolveContextMenuPosition,
+  getCanvasPointFromClient,
+}: ImageCanvasSidebarViewProps) {
+  if (!activeSidebarPanel) {
+    return null;
+  }
+
+  return (
+    <aside className="image-canvas-editor__sidebar" aria-label="图片资源栏">
+      <div className="image-canvas-editor__sidebar-header">
+        <div className="min-w-0">
+          <h2 className="image-canvas-editor__sidebar-title">
+            {activeSidebarPanel === 'assets' ? '素材' : '图层'}
+          </h2>
+          <div className="image-canvas-editor__sidebar-count">
+            {activeSidebarPanel === 'assets' ? assets.length : layers.length}
+          </div>
+        </div>
+        {activeSidebarPanel === 'assets' ? (
+          <div className="image-canvas-editor__sidebar-header-actions">
+            <EditorIconButton
+              className="image-canvas-editor__icon-button"
+              label="素材选择模式"
+              title="选择"
+              icon={isAssetSelectionMode ? CheckSquare : Square}
+              pressed={isAssetSelectionMode}
+              onClick={() =>
+                setIsAssetSelectionMode((currentMode) => !currentMode)
+              }
+            />
+            <EditorIconButton
+              className="image-canvas-editor__icon-button"
+              label="新建素材文件夹"
+              title="新建文件夹"
+              icon={FolderPlus}
+              onClick={() => setCreatingFolder(true)}
+            />
+          </div>
+        ) : (
+          <EditorIconButton
+            className="image-canvas-editor__icon-button"
+            label="图层打组"
+            title="打组"
+            icon={FolderPlus}
+            disabled={!selectedLayerId && selectedLayerIds.length === 0}
+            onClick={groupSelectedLayers}
+          />
+        )}
+      </div>
+
+      {activeSidebarPanel === 'assets' ? (
+        <ImageCanvasAssetLibraryPanelView
+          assetListRef={assetListRef}
+          assetPointerDragRef={assetPointerDragRef}
+          suppressAssetClickRef={suppressAssetClickRef}
+          groupedAssets={groupedAssets}
+          assetFolders={assetFolders}
+          isAssetSelectionMode={isAssetSelectionMode}
+          selectedAssetIds={selectedAssetIds}
+          assetMoveDropFolderId={assetMoveDropFolderId}
+          pinnedAssetMoveFolderId={pinnedAssetMoveFolderId}
+          creatingFolder={creatingFolder}
+          newFolderName={newFolderName}
+          renamingFolder={renamingFolder}
+          renamingAsset={renamingAsset}
+          allSelectableAssetsSelected={allSelectableAssetsSelected}
+          assetMarquee={assetMarquee}
+          setCreatingFolder={setCreatingFolder}
+          setNewFolderName={setNewFolderName}
+          setRenamingFolder={setRenamingFolder}
+          setRenamingAsset={setRenamingAsset}
+          setActiveUploadFolderId={setActiveUploadFolderId}
+          setUploadDropTarget={setUploadDropTarget}
+          setAssetPointerDrag={setAssetPointerDrag}
+          setSelectedAssetIds={setSelectedAssetIds}
+          onAssetMarqueePointerDown={onAssetMarqueePointerDown}
+          onAssetMarqueePointerMove={onAssetMarqueePointerMove}
+          onAssetMarqueePointerUp={onAssetMarqueePointerUp}
+          updateAssetMoveDropFolder={updateAssetMoveDropFolder}
+          addUploadedFiles={addUploadedFiles}
+          requestUpload={requestUpload}
+          moveAssetToFolder={moveAssetToFolder}
+          commitNewAssetFolder={commitNewAssetFolder}
+          toggleAssetFolder={toggleAssetFolder}
+          startRenamingFolder={startRenamingFolder}
+          commitFolderRename={commitFolderRename}
+          deleteAssetFolder={deleteAssetFolder}
+          startRenamingAsset={startRenamingAsset}
+          commitAssetRename={commitAssetRename}
+          deleteUploadedAsset={deleteUploadedAsset}
+          toggleAssetSelected={toggleAssetSelected}
+          addAssetLayer={addAssetLayer}
+          toggleAllAssetsSelected={toggleAllAssetsSelected}
+          deleteSelectedAssets={deleteSelectedAssets}
+          closeAssetSelectionMode={closeAssetSelectionMode}
+        />
+      ) : (
+        <ImageCanvasLayerPanelView
+          layers={layers}
+          selectedLayerId={selectedLayerId}
+          selectedLayerIds={selectedLayerIds}
+          setImageContextMenu={setImageContextMenu}
+          setContextMenu={setContextMenu}
+          selectSingleLayer={selectSingleLayer}
+          resolveContextMenuPosition={resolveContextMenuPosition}
+          getCanvasPointFromClient={getCanvasPointFromClient}
+        />
+      )}
+    </aside>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx b/src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx
new file mode 100644
index 000000000..6c93ebd9a
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSpecGenerationPanelView.test.tsx
@@ -0,0 +1,272 @@
+/* @vitest-environment jsdom */
+
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { createRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  GenerateDialogState,
+  SpecFormValues,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasSpecGenerationPanelView } from './ImageCanvasSpecGenerationPanelView';
+
+function createSpecDialog(
+  patch: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'spec',
+    prompt: '',
+    status: 'idle',
+    specType: 'character',
+    specValues: {
+      playSetting: 'RPG玩法',
+      artStyle: '像素风',
+      bodyRatio: '3',
+      characterView: '右向斜侧身站姿',
+      customPrompt: '',
+    },
+    ...patch,
+  };
+}
+
+function renderPanel({
+  dialog,
+  onUpdateSpecFormValue = vi.fn(),
+  onRequestUpload = vi.fn(),
+  onSubmit = vi.fn(),
+}: {
+  dialog: GenerateDialogState;
+  onUpdateSpecFormValue?: (key: keyof SpecFormValues, value: string) => void;
+  onRequestUpload?: (target: UploadTarget) => void;
+  onSubmit?: (dialog: GenerateDialogState) => void;
+}) {
+  render(
+    <ImageCanvasSpecGenerationPanelView
+      dialog={dialog}
+      style={{ left: 10, top: 20 }}
+      onUpdateSpecFormValue={onUpdateSpecFormValue}
+      onRequestUpload={onRequestUpload}
+      onSubmit={onSubmit}
+    />,
+  );
+}
+
+function UiDesignHarness({
+  initialDialog,
+}: {
+  initialDialog: GenerateDialogState;
+}) {
+  const [dialog, setDialog] = useState<GenerateDialogState | null>(
+    initialDialog,
+  );
+  const referenceButtonRef = createRef<HTMLButtonElement>();
+
+  return dialog ? (
+    <ImageCanvasSpecGenerationPanelView
+      dialog={dialog}
+      style={{ left: 10, top: 20 }}
+      generationReferenceButtonRef={referenceButtonRef}
+      setGenerateDialog={setDialog}
+      renderEditorPortal={(node) => node}
+      buildPortalMenuStyle={() => ({ position: 'fixed', left: 0, top: 0 })}
+      onUpdateSpecFormValue={vi.fn()}
+      onRequestUpload={vi.fn()}
+      onSubmit={vi.fn()}
+    />
+  ) : null;
+}
+
+describe('ImageCanvasSpecGenerationPanelView', () => {
+  it('keeps the reference row above fields for spec panels and shows mud point text', () => {
+    renderPanel({ dialog: createSpecDialog() });
+
+    const panel = screen.getByRole('dialog', { name: '生成规范' });
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    const submitButton = screen.getByRole('button', { name: '提交生成规范' });
+    expect(submitButton.textContent).toBe('生成5泥点');
+    const dimensionsButton = screen.getByRole('button', {
+      name: '生成图片尺寸 16:9·2K',
+    }) as HTMLButtonElement;
+    const modelButton = screen.getByRole('button', {
+      name: '生成图片模型 gpt-image-2',
+    }) as HTMLButtonElement;
+
+    expect(dimensionsButton.disabled).toBe(true);
+    expect(modelButton.disabled).toBe(true);
+    expect(dimensionsButton.className).toContain(
+      'image-canvas-editor__option-cluster--dimensions',
+    );
+    expect(modelButton.className).toContain(
+      'image-canvas-editor__option-cluster--model',
+    );
+    fireEvent.click(dimensionsButton);
+    fireEvent.click(modelButton);
+    expect(screen.queryByRole('menu', { name: '生成图片尺寸选项' })).toBeNull();
+    expect(screen.queryByRole('menu', { name: '生成图片模型选项' })).toBeNull();
+  });
+
+  it('renders UI design as a single borderless prompt below the first reference row', () => {
+    render(
+      <UiDesignHarness
+        initialDialog={{
+          mode: 'ui-design',
+          prompt: '',
+          status: 'idle',
+          composerOpen: true,
+          uiDesignSpecReference: null,
+          imageModel: 'nanobanana2',
+          aspectRatio: '16:9',
+          imageSize: '1K',
+        }}
+      />,
+    );
+
+    const panel = screen.getByRole('dialog', { name: '生成UI设计图' });
+    const prompt = screen.getByRole('textbox', { name: 'UI设计要求' });
+
+    expect(
+      panel.firstElementChild?.className.includes(
+        'image-canvas-editor__reference-strip',
+      ),
+    ).toBe(true);
+    expect(panel.textContent).not.toContain('UI设计要求');
+    expect(prompt.getAttribute('placeholder')).toBe(
+      '你希望这个 UI 长什么样？',
+    );
+    expect(prompt.className).toContain(
+      'image-canvas-editor__generation-prompt--borderless',
+    );
+    const submitButton = screen.getByRole('button', { name: '生成UI设计图' });
+    expect(submitButton.textContent).toBe('生成12泥点');
+    fireEvent.click(screen.getByRole('button', { name: '生成图片模型 nanobanana2' }));
+    fireEvent.click(screen.getByRole('button', { name: 'gpt-image-2' }));
+    expect(screen.getByRole('button', { name: '生成UI设计图' }).textContent).toBe(
+      '生成20泥点',
+    );
+  });
+
+  it('renders character spec fields and forwards updates', () => {
+    const updateSpecFormValue = vi.fn();
+    renderPanel({
+      dialog: createSpecDialog(),
+      onUpdateSpecFormValue: updateSpecFormValue,
+    });
+
+    fireEvent.change(screen.getByLabelText('玩法设定'), {
+      target: { value: '战棋玩法' },
+    });
+    fireEvent.change(screen.getByLabelText('美术风格'), {
+      target: { value: '水彩' },
+    });
+    fireEvent.change(screen.getByLabelText('头身比'), {
+      target: { value: '5' },
+    });
+    fireEvent.change(screen.getByLabelText('角色视角'), {
+      target: { value: '左向三分之二侧身站姿' },
+    });
+
+    expect(updateSpecFormValue).toHaveBeenCalledWith('playSetting', '战棋玩法');
+    expect(updateSpecFormValue).toHaveBeenCalledWith('artStyle', '水彩');
+    expect(updateSpecFormValue).toHaveBeenCalledWith('bodyRatio', '5');
+    expect(updateSpecFormValue).toHaveBeenCalledWith(
+      'characterView',
+      '左向三分之二侧身站姿',
+    );
+  });
+
+  it('renders custom prompt and hides reference upload for icon specs', () => {
+    const updateSpecFormValue = vi.fn();
+    renderPanel({
+      dialog: createSpecDialog({
+        specType: 'custom',
+        specValues: {
+          playSetting: '',
+          artStyle: '',
+          bodyRatio: '3',
+          characterView: '',
+          customPrompt: '自定义提示',
+        },
+      }),
+      onUpdateSpecFormValue: updateSpecFormValue,
+    });
+
+    fireEvent.change(screen.getByLabelText('自定义规范提示词'), {
+      target: { value: '新的规范提示' },
+    });
+
+    expect(updateSpecFormValue).toHaveBeenCalledWith(
+      'customPrompt',
+      '新的规范提示',
+    );
+
+    cleanup();
+    renderPanel({ dialog: createSpecDialog({ specType: 'icon' }) });
+
+    expect(screen.getByRole('button', { name: '参考图' })).toBeTruthy();
+  });
+
+  it('requests reference upload and submits while idle', () => {
+    const requestUpload = vi.fn();
+    const submitSpec = vi.fn();
+    const dialog = createSpecDialog();
+    renderPanel({
+      dialog,
+      onRequestUpload: requestUpload,
+      onSubmit: submitSpec,
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '参考图' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交生成规范' }));
+
+    expect(requestUpload).toHaveBeenCalledWith('spec-reference');
+    expect(submitSpec).toHaveBeenCalledWith(dialog);
+  });
+
+  it('renders compact spec submit cost with mud point text', () => {
+    renderPanel({ dialog: createSpecDialog() });
+
+    const submitButton = screen.getByRole('button', { name: '提交生成规范' });
+
+    expect(submitButton.textContent).toBe('生成5泥点');
+  });
+
+  it('disables controls while generating and renders failure state', () => {
+    const submitSpec = vi.fn();
+    const { rerender } = render(
+      <ImageCanvasSpecGenerationPanelView
+        dialog={createSpecDialog({ status: 'generating' })}
+        style={{ left: 10, top: 20 }}
+        onUpdateSpecFormValue={vi.fn()}
+        onRequestUpload={vi.fn()}
+        onSubmit={submitSpec}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交生成规范' }));
+
+    expect((screen.getByLabelText('玩法设定') as HTMLInputElement).disabled).toBe(
+      true,
+    );
+    expect(submitSpec).not.toHaveBeenCalled();
+
+    rerender(
+      <ImageCanvasSpecGenerationPanelView
+        dialog={createSpecDialog({
+          status: 'failed',
+          errorMessage: '生成失败',
+        })}
+        style={{ left: 10, top: 20 }}
+        onUpdateSpecFormValue={vi.fn()}
+        onRequestUpload={vi.fn()}
+        onSubmit={submitSpec}
+      />,
+    );
+
+    expect(screen.getByRole('alert').textContent).toContain('生成失败');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasSpecGenerationPanelView.tsx b/src/components/image-editor/ImageCanvasSpecGenerationPanelView.tsx
new file mode 100644
index 000000000..8860b8a57
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasSpecGenerationPanelView.tsx
@@ -0,0 +1,464 @@
+import { ClipboardList, Cpu, ImagePlus } from 'lucide-react';
+import {
+  type CSSProperties,
+  type Dispatch,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformFieldLabel } from '../common/PlatformFieldLabel';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformInlineOptionButton } from '../common/PlatformInlineOptionButton';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import {
+  PlatformSelectField,
+  PlatformTextField,
+} from '../common/PlatformTextField';
+import type {
+  GenerateDialogState,
+  SpecFormValues,
+  SpecGenerationType,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationImageOptionsView } from './ImageCanvasGenerationImageOptionsView';
+import {
+  calculateEditorSpecGenerationPrice,
+  calculateEditorUiDesignPrice,
+  CHARACTER_SPEC_VIEW_OPTIONS,
+  getEditorImageModelDisplayName,
+  resolveEditorImageSizeLabel,
+  SPEC_GENERATION_ASPECT_RATIO,
+  SPEC_GENERATION_IMAGE_SIZE,
+  SPEC_GENERATION_MODEL,
+} from './ImageCanvasGenerationModel';
+import { ImageCanvasReferenceSlot } from './ImageCanvasReferenceSlot';
+import { useImageCanvasFloatingOptionDismiss } from './useImageCanvasFloatingOptionDismiss';
+
+type ImageCanvasSpecGenerationPanelViewProps = {
+  dialog: GenerateDialogState;
+  style: CSSProperties;
+  isGenerationReferenceMenuOpen?: boolean;
+  generationReferenceButtonRef?: RefObject<HTMLButtonElement | null>;
+  setIsGenerationReferenceMenuOpen?: Dispatch<SetStateAction<boolean>>;
+  setIsPickingGenerationReferenceFromCanvas?: Dispatch<SetStateAction<boolean>>;
+  setGenerateDialog?: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  renderEditorPortal?: (node: ReactNode) => ReactNode;
+  buildPortalMenuStyle?: (
+    anchor: HTMLElement | null,
+    placement: 'above' | 'below',
+  ) => CSSProperties;
+  onOpenSpecDialog?: (specType: SpecGenerationType) => void;
+  onUpdateSpecFormValue: (key: keyof SpecFormValues, value: string) => void;
+  onRequestUpload: (target: UploadTarget) => void;
+  onRememberImageModel?: (model: string) => void;
+  onSubmit: (dialog: GenerateDialogState) => void;
+};
+
+export function ImageCanvasSpecGenerationPanelView({
+  dialog,
+  style,
+  isGenerationReferenceMenuOpen = false,
+  generationReferenceButtonRef,
+  setIsGenerationReferenceMenuOpen,
+  setIsPickingGenerationReferenceFromCanvas,
+  setGenerateDialog,
+  renderEditorPortal = (node) => node,
+  buildPortalMenuStyle = () => ({}),
+  onOpenSpecDialog,
+  onUpdateSpecFormValue,
+  onRequestUpload,
+  onRememberImageModel = () => {},
+  onSubmit,
+}: ImageCanvasSpecGenerationPanelViewProps) {
+  const isUiDesignDialog = dialog.mode === 'ui-design';
+  const specSizeLabel = resolveEditorImageSizeLabel({
+    aspectRatio: SPEC_GENERATION_ASPECT_RATIO,
+    imageSize: SPEC_GENERATION_IMAGE_SIZE,
+  });
+  const specModelLabel = getEditorImageModelDisplayName(SPEC_GENERATION_MODEL);
+  const referenceLabel = isUiDesignDialog ? 'UI设计图标规范' : '参考图';
+  const referenceSlotLabel = isUiDesignDialog
+    ? '图标规范'
+    : dialog.specType === 'character'
+      ? '角色规范'
+      : '参考图';
+  const uploadTarget: UploadTarget = isUiDesignDialog
+    ? 'ui-design-icon-spec'
+    : 'spec-reference';
+  const reference = isUiDesignDialog
+    ? dialog.uiDesignSpecReference
+    : dialog.specReference;
+  const isGenerating = dialog.status === 'generating';
+  const specGenerationCost = calculateEditorSpecGenerationPrice(
+    SPEC_GENERATION_MODEL,
+  );
+  useImageCanvasFloatingOptionDismiss({
+    isOpen: isGenerationReferenceMenuOpen,
+    boundaryRefs: [generationReferenceButtonRef],
+    onDismiss: () => setIsGenerationReferenceMenuOpen?.(false),
+  });
+
+  const openReferenceMenu = () => {
+    if (setIsGenerationReferenceMenuOpen) {
+      setIsGenerationReferenceMenuOpen((open) => !open);
+      return;
+    }
+    onRequestUpload(uploadTarget);
+  };
+
+  return (
+    <>
+      <form
+        className="image-canvas-editor__generation-composer image-canvas-editor__generation-composer--image image-canvas-editor__spec-composer"
+        style={style}
+        role="dialog"
+        aria-label={isUiDesignDialog ? '生成UI设计图' : '生成规范'}
+        onPointerDown={(event) => event.stopPropagation()}
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (dialog.status !== 'generating') {
+            onSubmit(dialog);
+          }
+        }}
+      >
+      <div className="image-canvas-editor__reference-strip">
+        {(isUiDesignDialog || dialog.specType) ? (
+          <ImageCanvasReferenceSlot
+            buttonRef={generationReferenceButtonRef}
+            tone={isUiDesignDialog ? 'ui' : 'spec'}
+            icon={
+              isUiDesignDialog ? (
+                <ImagePlus className="h-4 w-4" aria-hidden="true" />
+              ) : (
+                <ClipboardList className="h-4 w-4" aria-hidden="true" />
+              )
+            }
+            imageSrc={reference?.src}
+            label={referenceSlotLabel}
+            ariaLabel={referenceLabel}
+            title={reference?.label ?? referenceLabel}
+            disabled={isGenerating}
+            isAdd={!reference}
+            onClick={openReferenceMenu}
+            onRemove={
+              reference && setGenerateDialog
+                ? () =>
+                    setGenerateDialog((currentDialog) => {
+                      if (isUiDesignDialog) {
+                        return currentDialog?.mode === 'ui-design'
+                          ? {
+                              ...currentDialog,
+                              status:
+                                currentDialog.status === 'failed'
+                                  ? 'idle'
+                                  : currentDialog.status,
+                              errorMessage:
+                                currentDialog.status === 'failed'
+                                  ? undefined
+                                  : currentDialog.errorMessage,
+                              uiDesignSpecReference: null,
+                            }
+                          : currentDialog;
+                      }
+                      return currentDialog?.mode === 'spec'
+                        ? {
+                            ...currentDialog,
+                            status:
+                              currentDialog.status === 'failed'
+                                ? 'idle'
+                                : currentDialog.status,
+                            errorMessage:
+                              currentDialog.status === 'failed'
+                                ? undefined
+                                : currentDialog.errorMessage,
+                            specReference: null,
+                          }
+                        : currentDialog;
+                    })
+                : undefined
+            }
+            removeLabel={`删除${referenceLabel}`}
+          />
+        ) : null}
+      </div>
+      <div className="image-canvas-editor__spec-fields">
+        {isUiDesignDialog ? (
+          <label className="image-canvas-editor__field-block image-canvas-editor__field-block--single">
+            <PlatformTextField
+              variant="textarea"
+              aria-label="UI设计要求"
+              value={dialog.prompt}
+              disabled={isGenerating}
+              placeholder="你希望这个 UI 长什么样？"
+              size="sm"
+              density="compact"
+              className="image-canvas-editor__generation-prompt image-canvas-editor__generation-prompt--borderless"
+              onChange={(event) => {
+                const nextPrompt = event.target.value;
+                if (setGenerateDialog) {
+                  setGenerateDialog((currentDialog) =>
+                    currentDialog?.mode === 'ui-design'
+                      ? {
+                          ...currentDialog,
+                          prompt: nextPrompt,
+                          status:
+                            currentDialog.status === 'failed'
+                              ? 'idle'
+                              : currentDialog.status,
+                          errorMessage:
+                            currentDialog.status === 'failed'
+                              ? undefined
+                              : currentDialog.errorMessage,
+                        }
+                      : currentDialog,
+                  );
+                  return;
+                }
+                onUpdateSpecFormValue('customPrompt', nextPrompt);
+              }}
+            />
+          </label>
+        ) : dialog.specType === 'custom' ? (
+          <label className="image-canvas-editor__field-block">
+            <PlatformFieldLabel
+              variant="form"
+              className="image-canvas-editor__field-title"
+            >
+              自定义规范提示词
+            </PlatformFieldLabel>
+            <PlatformTextField
+              variant="textarea"
+              aria-label="自定义规范提示词"
+              value={dialog.specValues?.customPrompt ?? ''}
+              disabled={isGenerating}
+              size="sm"
+              density="compact"
+              className="image-canvas-editor__spec-textarea"
+              onChange={(event) =>
+                onUpdateSpecFormValue('customPrompt', event.target.value)
+              }
+            />
+          </label>
+        ) : (
+          <>
+            <label className="image-canvas-editor__field-block">
+              <PlatformFieldLabel
+                variant="form"
+                className="image-canvas-editor__field-title"
+              >
+                玩法设定
+              </PlatformFieldLabel>
+              <PlatformTextField
+                aria-label="玩法设定"
+                value={dialog.specValues?.playSetting ?? ''}
+                disabled={isGenerating}
+                size="sm"
+                density="compact"
+                className="image-canvas-editor__spec-input"
+                onChange={(event) =>
+                  onUpdateSpecFormValue('playSetting', event.target.value)
+                }
+              />
+            </label>
+            <label className="image-canvas-editor__field-block">
+              <PlatformFieldLabel
+                variant="form"
+                className="image-canvas-editor__field-title"
+              >
+                美术风格
+              </PlatformFieldLabel>
+              <PlatformTextField
+                aria-label="美术风格"
+                value={dialog.specValues?.artStyle ?? ''}
+                disabled={isGenerating}
+                size="sm"
+                density="compact"
+                className="image-canvas-editor__spec-input"
+                onChange={(event) =>
+                  onUpdateSpecFormValue('artStyle', event.target.value)
+                }
+              />
+            </label>
+            {dialog.specType === 'character' ? (
+              <>
+                <label className="image-canvas-editor__field-block">
+                  <PlatformFieldLabel
+                    variant="form"
+                    className="image-canvas-editor__field-title"
+                  >
+                    头身比
+                  </PlatformFieldLabel>
+                  <PlatformSelectField
+                    aria-label="头身比"
+                    value={dialog.specValues?.bodyRatio ?? '3'}
+                    disabled={isGenerating}
+                    size="sm"
+                    density="compact"
+                    className="image-canvas-editor__spec-input"
+                    onChange={(event) =>
+                      onUpdateSpecFormValue('bodyRatio', event.target.value)
+                    }
+                  >
+                    {['2', '3', '4', '5', '6'].map((value) => (
+                      <option key={value} value={value}>
+                        {value}
+                      </option>
+                    ))}
+                  </PlatformSelectField>
+                </label>
+                <label className="image-canvas-editor__field-block">
+                  <PlatformFieldLabel
+                    variant="form"
+                    className="image-canvas-editor__field-title"
+                  >
+                    角色视角
+                  </PlatformFieldLabel>
+                  <PlatformSelectField
+                    aria-label="角色视角"
+                    value={dialog.specValues?.characterView ?? ''}
+                    disabled={isGenerating}
+                    size="sm"
+                    density="compact"
+                    className="image-canvas-editor__spec-input"
+                    onChange={(event) =>
+                      onUpdateSpecFormValue('characterView', event.target.value)
+                    }
+                  >
+                    {CHARACTER_SPEC_VIEW_OPTIONS.map((value) => (
+                      <option key={value} value={value}>
+                        {value}
+                      </option>
+                    ))}
+                  </PlatformSelectField>
+                </label>
+              </>
+            ) : null}
+          </>
+        )}
+      </div>
+      {dialog.status === 'failed' ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status"
+          role="alert"
+        >
+          {dialog.errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+      <div className="image-canvas-editor__generation-composer-footer image-canvas-editor__spec-footer">
+        {isUiDesignDialog ? (
+          <ImageCanvasGenerationImageOptionsView
+            dialog={dialog}
+            setGenerateDialog={setGenerateDialog ?? (() => undefined)}
+            includeDimensions
+            onRememberImageModel={onRememberImageModel}
+            cost={calculateEditorUiDesignPrice(dialog.imageModel)}
+            submitLabel="生成"
+            submitAriaLabel="生成UI设计图"
+            optionLabelPrefix="生成图片"
+            renderEditorPortal={renderEditorPortal}
+            buildPortalMenuStyle={buildPortalMenuStyle}
+          />
+        ) : (
+          <>
+            <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--dimensions image-canvas-editor__readonly-generation-option">
+              <PlatformInlineOptionButton
+                className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--dimensions"
+                aria-label={`生成图片尺寸 ${specSizeLabel}`}
+                disabled
+              >
+                {specSizeLabel}
+              </PlatformInlineOptionButton>
+            </div>
+            <div className="image-canvas-editor__option-popover-anchor image-canvas-editor__option-popover-anchor--model image-canvas-editor__readonly-generation-option">
+              <PlatformInlineOptionButton
+                className="image-canvas-editor__option-cluster image-canvas-editor__option-cluster--model"
+                aria-label={`生成图片模型 ${specModelLabel}`}
+                disabled
+              >
+                <span className="image-canvas-editor__model-trigger-label">
+                  <span
+                    className="image-canvas-editor__model-icon"
+                    aria-hidden="true"
+                  >
+                    <Cpu />
+                  </span>
+                  <span>{specModelLabel}</span>
+                </span>
+              </PlatformInlineOptionButton>
+            </div>
+            <PlatformActionButton
+              type="submit"
+              tone="secondary"
+              size="xs"
+              shape="pill"
+              className="image-canvas-editor__generation-submit image-canvas-editor__spec-submit"
+              disabled={isGenerating}
+              aria-label="提交生成规范"
+            >
+              {isGenerating ? (
+                '生成中'
+              ) : (
+                <>
+                  <span>生成</span>
+                  <span className="image-canvas-editor__mud-point-inline">
+                    {specGenerationCost}泥点
+                  </span>
+                </>
+              )}
+            </PlatformActionButton>
+          </>
+        )}
+      </div>
+      </form>
+      {isGenerationReferenceMenuOpen && generationReferenceButtonRef
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu"
+              label="参考图来源"
+              placement="top-start"
+              style={buildPortalMenuStyle(
+                generationReferenceButtonRef.current,
+                'above',
+              )}
+            >
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen?.(false);
+                  setIsPickingGenerationReferenceFromCanvas?.(true);
+                }}
+              >
+                从画布中选择
+              </PlatformFloatingMenuItem>
+              {isUiDesignDialog ? (
+                <PlatformFloatingMenuItem
+                  onClick={() => {
+                    setIsGenerationReferenceMenuOpen?.(false);
+                    onOpenSpecDialog?.('icon');
+                  }}
+                >
+                  新建图标规范
+                </PlatformFloatingMenuItem>
+              ) : null}
+              <PlatformFloatingMenuItem
+                onClick={() => {
+                  setIsGenerationReferenceMenuOpen?.(false);
+                  setIsPickingGenerationReferenceFromCanvas?.(false);
+                  onRequestUpload(uploadTarget);
+                }}
+              >
+                上传图片
+              </PlatformFloatingMenuItem>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasStageControllerModel.test.ts b/src/components/image-editor/ImageCanvasStageControllerModel.test.ts
new file mode 100644
index 000000000..a98949305
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasStageControllerModel.test.ts
@@ -0,0 +1,128 @@
+/* @vitest-environment jsdom */
+
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasContextMenuState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  createBlankCanvasContextMenu,
+  createLayerCanvasContextMenus,
+  resolveImageCanvasStageControllerModel,
+} from './ImageCanvasStageControllerModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 80,
+    width: 240,
+    height: 120,
+    originalWidth: 240,
+    originalHeight: 120,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasStageControllerModel', () => {
+  it('derives selected layer, selected toolbar, and context image target', () => {
+    const selectedLayer = createLayer({ id: 'selected', x: 40, y: 60 });
+    const generatedLayer = createLayer({
+      id: 'generated',
+      x: 200,
+      y: 160,
+      width: 320,
+      height: 180,
+    });
+
+    const model = resolveImageCanvasStageControllerModel({
+      layers: [selectedLayer, generatedLayer],
+      selectedLayerId: selectedLayer.id,
+      selectedLayerIds: [selectedLayer.id, generatedLayer.id],
+      imageContextMenu: { layerId: generatedLayer.id, x: 0, y: 0 },
+      contextMenu: null,
+      viewport: { x: 10, y: 20, scale: 2 },
+      canvasSize: { width: 900, height: 640 },
+    });
+
+    expect(model.selectedLayer).toBe(selectedLayer);
+    expect(model.selectedLayerCount).toBe(2);
+    expect(model.hasMultipleSelectedLayers).toBe(true);
+    expect(model.selectedToolbarStyle).toEqual({ left: 330, top: 128 });
+    expect(model.imageContextMenuLayer).toBe(generatedLayer);
+  });
+
+  it('derives context target state from a layer menu and current selection', () => {
+    const visibleLayer = createLayer({ id: 'visible', locked: true });
+    const hiddenLayer = createLayer({ id: 'hidden', hidden: true });
+    const contextMenu: CanvasContextMenuState = {
+      kind: 'layer',
+      layerId: hiddenLayer.id,
+      x: 20,
+      y: 30,
+      canvasPoint: { x: 40, y: 50 },
+    };
+
+    const model = resolveImageCanvasStageControllerModel({
+      layers: [visibleLayer, hiddenLayer],
+      selectedLayerId: visibleLayer.id,
+      selectedLayerIds: [visibleLayer.id, hiddenLayer.id],
+      imageContextMenu: null,
+      contextMenu,
+      viewport: { x: 0, y: 0, scale: 1 },
+      canvasSize: { width: 900, height: 640 },
+    });
+
+    expect(model.contextTargetIds).toEqual([visibleLayer.id, hiddenLayer.id]);
+    expect(model.contextTargetLayers).toEqual([visibleLayer, hiddenLayer]);
+    expect(model.contextShouldShowLayer).toBe(true);
+    expect(model.contextShouldUnlockLayer).toBe(true);
+  });
+
+  it('creates clamped blank and layer context menus with canvas points', () => {
+    window.innerWidth = 320;
+    window.innerHeight = 240;
+
+    expect(
+      createBlankCanvasContextMenu({
+        clientX: 1000,
+        clientY: 1000,
+        canvasPoint: { x: 12, y: 16 },
+      }),
+    ).toEqual({
+      kind: 'blank',
+      x: 124,
+      y: 56,
+      canvasPoint: { x: 12, y: 16 },
+    });
+
+    expect(
+      createLayerCanvasContextMenus({
+        clientX: 1000,
+        clientY: 1000,
+        layerId: 'layer-a',
+        canvasPoint: { x: 20, y: 30 },
+      }),
+    ).toEqual({
+      contextMenu: {
+        kind: 'layer',
+        layerId: 'layer-a',
+        x: 124,
+        y: 8,
+        canvasPoint: { x: 20, y: 30 },
+      },
+      imageContextMenu: {
+        layerId: 'layer-a',
+        x: 124,
+        y: 8,
+      },
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasStageControllerModel.ts b/src/components/image-editor/ImageCanvasStageControllerModel.ts
new file mode 100644
index 000000000..c60b46602
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasStageControllerModel.ts
@@ -0,0 +1,137 @@
+import {
+  getCanvasLayersByIds,
+  resolveContextTargetLayerIds,
+} from './ImageCanvasLayerCommandModel';
+import {
+  resolveContextMenuPosition,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+import {
+  resolveSelectedToolbarStyle,
+} from './ImageCanvasOverlayModel';
+import {
+  getSelectedGenerationDialogIds,
+  getSelectedLayerIds,
+} from './ImageCanvasSelectionModel';
+
+export type ImageCanvasStageControllerModel = {
+  selectedLayer: CanvasLayer | null;
+  selectedLayerCount: number;
+  hasMultipleSelectedLayers: boolean;
+  selectedToolbarStyle: ReturnType<typeof resolveSelectedToolbarStyle>;
+  imageContextMenuLayer: CanvasLayer | null;
+  contextTargetIds: string[];
+  contextTargetLayers: CanvasLayer[];
+  contextShouldShowLayer: boolean;
+  contextShouldUnlockLayer: boolean;
+};
+
+type ResolveImageCanvasStageControllerModelOptions = {
+  layers: CanvasLayer[];
+  canvasGenerationDialogs?: CanvasGenerationDialogState[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  imageContextMenu: ImageContextMenuState | null;
+  contextMenu: CanvasContextMenuState | null;
+  viewport: CanvasViewport;
+  canvasSize: { width: number; height: number };
+};
+
+export function resolveImageCanvasStageControllerModel({
+  layers,
+  canvasGenerationDialogs = [],
+  selectedLayerId,
+  selectedLayerIds,
+  imageContextMenu,
+  contextMenu,
+  viewport,
+  canvasSize,
+}: ResolveImageCanvasStageControllerModelOptions): ImageCanvasStageControllerModel {
+  const selectedLayer =
+    layers.find((layer) => layer.id === selectedLayerId) ?? null;
+  const selectedCanvasLayerIds = getSelectedLayerIds(selectedLayerIds);
+  const selectedGenerationDialogIds =
+    getSelectedGenerationDialogIds(selectedLayerIds);
+  const selectedLayerCount =
+    selectedCanvasLayerIds.filter((layerId) =>
+      layers.some((layer) => layer.id === layerId),
+    ).length +
+    selectedGenerationDialogIds.filter((dialogId) =>
+      canvasGenerationDialogs.some((dialog) => dialog.id === dialogId),
+    ).length;
+  const imageContextMenuLayer = imageContextMenu
+    ? (layers.find((layer) => layer.id === imageContextMenu.layerId) ?? null)
+    : null;
+  const contextTargetIds = resolveContextTargetLayerIds(
+    contextMenu,
+    selectedLayerIds,
+  );
+  const contextTargetLayers = getCanvasLayersByIds(layers, contextTargetIds);
+
+  return {
+    selectedLayer,
+    selectedLayerCount,
+    hasMultipleSelectedLayers: selectedLayerCount > 1,
+    selectedToolbarStyle: resolveSelectedToolbarStyle({
+      selectedLayer,
+      viewport,
+      canvasSize,
+    }),
+    imageContextMenuLayer,
+    contextTargetIds,
+    contextTargetLayers,
+    contextShouldShowLayer: contextTargetLayers.some((layer) => layer.hidden),
+    contextShouldUnlockLayer: contextTargetLayers.some((layer) => layer.locked),
+  };
+}
+
+export function createBlankCanvasContextMenu({
+  clientX,
+  clientY,
+  canvasPoint,
+}: {
+  clientX: number;
+  clientY: number;
+  canvasPoint: { x: number; y: number };
+}): CanvasContextMenuState {
+  return {
+    kind: 'blank',
+    ...resolveContextMenuPosition(clientX, clientY, 'blank'),
+    canvasPoint,
+  };
+}
+
+export function createLayerCanvasContextMenus({
+  clientX,
+  clientY,
+  layerId,
+  canvasPoint,
+}: {
+  clientX: number;
+  clientY: number;
+  layerId: string;
+  canvasPoint: { x: number; y: number };
+}): {
+  contextMenu: CanvasContextMenuState;
+  imageContextMenu: ImageContextMenuState;
+} {
+  const position = resolveContextMenuPosition(clientX, clientY, 'layer');
+  return {
+    contextMenu: {
+      kind: 'layer',
+      layerId,
+      ...position,
+      canvasPoint,
+    },
+    imageContextMenu: {
+      layerId,
+      ...position,
+    },
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts b/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts
new file mode 100644
index 000000000..191c5f1c6
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasStageInteractionModel.test.ts
@@ -0,0 +1,368 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import {
+  createGenerationFrameSelectionStart,
+  createCanvasMarqueeState,
+  createGenerationFrameDragState,
+  createLayerDragStart,
+  createMinimapDragState,
+  createPanDragState,
+  getCanvasPointFromPointer,
+  getPointerButton,
+  getPointerClient,
+  getPointerId,
+  resolveLayerPointerSelection,
+  updateGenerateDialogForLayerClick,
+  updateGenerateDialogForLayerPointerDown,
+  updateMinimapDragMovement,
+} from './ImageCanvasStageInteractionModel';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 120,
+    width: 240,
+    height: 160,
+    originalWidth: 240,
+    originalHeight: 160,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasStageInteractionModel', () => {
+  it('normalizes pointer button, client point, and pointer id', () => {
+    expect(
+      getPointerButton({
+        button: 0,
+        buttons: 1,
+        nativeEvent: { button: 0, buttons: 4 },
+      }),
+    ).toBe(1);
+    expect(
+      getPointerButton({
+        button: 2,
+        buttons: 0,
+        nativeEvent: { button: 0, buttons: 0 },
+      }),
+    ).toBe(2);
+    expect(
+      getPointerClient({
+        clientX: Number.NaN,
+        clientY: 42,
+        nativeEvent: { clientX: 120, clientY: 80 },
+      }),
+    ).toEqual({ x: 120, y: 42 });
+    expect(
+      getPointerId({
+        pointerId: Number.NaN,
+        nativeEvent: { pointerId: 18 },
+      }),
+    ).toBe(18);
+    expect(getPointerId({})).toBe(-1);
+  });
+
+  it('creates pan and marquee states from normalized pointer positions', () => {
+    expect(
+      getCanvasPointFromPointer({
+        pointer: { x: 180, y: 140 },
+        rect: { left: 20, top: 30 },
+      }),
+    ).toEqual({ x: 160, y: 110 });
+    expect(
+      createCanvasMarqueeState({
+        pointerId: 8,
+        pointer: { x: 180, y: 140 },
+        rect: { left: 20, top: 30 },
+      }),
+    ).toEqual({
+      pointerId: 8,
+      startX: 160,
+      startY: 110,
+      currentX: 160,
+      currentY: 110,
+    });
+    expect(
+      createPanDragState({
+        pointerId: 9,
+        pointer: { x: 320, y: 240 },
+        viewport: { x: 10, y: 20, scale: 1.5 },
+      }),
+    ).toEqual({
+      kind: 'pan',
+      pointerId: 9,
+      startClientX: 320,
+      startClientY: 240,
+      startViewport: { x: 10, y: 20, scale: 1.5 },
+    });
+  });
+
+  it('resolves multi-select layer toggles without emptying the last selection', () => {
+    expect(
+      resolveLayerPointerSelection({
+        layerId: 'a',
+        selectedLayerIds: ['b'],
+        isMultiSelectGesture: false,
+      }),
+    ).toEqual(['a']);
+    expect(
+      resolveLayerPointerSelection({
+        layerId: 'a',
+        selectedLayerIds: ['b'],
+        isMultiSelectGesture: true,
+      }),
+    ).toEqual(['b', 'a']);
+    expect(
+      resolveLayerPointerSelection({
+        layerId: 'b',
+        selectedLayerIds: ['a', 'b'],
+        isMultiSelectGesture: true,
+      }),
+    ).toEqual(['a']);
+    expect(
+      resolveLayerPointerSelection({
+        layerId: 'a',
+        selectedLayerIds: ['a'],
+        isMultiSelectGesture: true,
+      }),
+    ).toEqual(['a']);
+  });
+
+  it('creates layer drag state for the next selected layer group', () => {
+    const layers = [
+      createLayer({ id: 'a', x: 40, y: 50 }),
+      createLayer({ id: 'b', x: 120, y: 150 }),
+      createLayer({ id: 'c', x: 220, y: 250 }),
+    ];
+
+    expect(
+      createLayerDragStart({
+        layer: layers[1]!,
+        layers,
+        generationDialogs: [],
+        selectedLayerIds: ['a'],
+        isMultiSelectGesture: true,
+        pointerId: 4,
+        pointer: { x: 300, y: 260 },
+        viewportScale: 1.25,
+      }),
+    ).toEqual({
+      selectedLayerIds: ['a', 'b'],
+      selectedLayerId: 'b',
+      dragState: {
+        kind: 'layer',
+        pointerId: 4,
+        layerId: 'b',
+        layerIds: ['a', 'b'],
+        generationDialogIds: [],
+        startClientX: 300,
+        startClientY: 260,
+        startLayerX: 120,
+        startLayerY: 150,
+        startLayers: [
+          { id: 'a', x: 40, y: 50 },
+          { id: 'b', x: 120, y: 150 },
+        ],
+        startGenerationFrames: [],
+        startScale: 1.25,
+      },
+    });
+  });
+
+  it('closes canvas generation composers when clicking existing layers', () => {
+    const generatedDialog: GenerateDialogState = {
+      id: 'dialog-1',
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      composerOpen: false,
+      generatedLayerId: 'layer-a',
+    };
+    const editDialog: GenerateDialogState = {
+      mode: 'edit',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+      sourceLayerId: 'layer-a',
+    };
+    const draftDialogWithoutId: GenerateDialogState = {
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      composerOpen: true,
+    };
+
+    expect(
+      updateGenerateDialogForLayerPointerDown(generatedDialog, 'layer-a'),
+    ).toEqual({
+      ...generatedDialog,
+      composerOpen: false,
+    });
+    expect(
+      updateGenerateDialogForLayerPointerDown(generatedDialog, 'layer-b'),
+    ).toEqual({
+      ...generatedDialog,
+      composerOpen: false,
+    });
+    expect(updateGenerateDialogForLayerPointerDown(editDialog, 'layer-a')).toBe(
+      editDialog,
+    );
+    expect(updateGenerateDialogForLayerClick(generatedDialog)).toEqual({
+      ...generatedDialog,
+      composerOpen: false,
+    });
+    expect(
+      updateGenerateDialogForLayerClick(draftDialogWithoutId),
+    ).toMatchObject({
+      mode: 'generate',
+      composerOpen: false,
+    });
+    expect(updateGenerateDialogForLayerClick(editDialog)).toBe(editDialog);
+  });
+
+  it('creates generation frame and minimap drag states', () => {
+    const dialog: CanvasGenerationDialogState = {
+      id: 'dialog-1',
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      placeholder: {
+        x: 200,
+        y: 160,
+        width: 420,
+        height: 420,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+    };
+
+    expect(
+      createGenerationFrameDragState({
+        dialog,
+        pointerId: 11,
+        pointer: { x: 240, y: 200 },
+        viewportScale: 2,
+      }),
+    ).toEqual({
+      kind: 'generation-frame',
+      dialogId: 'dialog-1',
+      dialogIds: ['dialog-1'],
+      layerIds: [],
+      pointerId: 11,
+      startClientX: 240,
+      startClientY: 200,
+      startFrameX: 200,
+      startFrameY: 160,
+      startFrames: [{ id: 'dialog-1', x: 200, y: 160 }],
+      startLayers: [],
+      startScale: 2,
+    });
+    expect(
+      createGenerationFrameDragState({
+        dialog: { ...dialog, placeholder: undefined },
+        pointerId: 11,
+        pointer: { x: 240, y: 200 },
+        viewportScale: 2,
+      }),
+    ).toBeNull();
+
+    const minimapDrag = createMinimapDragState({
+      pointerId: 12,
+      pointer: { x: 120, y: 90 },
+      viewport: { x: 10, y: 20, scale: 1 },
+      minimapScale: 0.4,
+    });
+    expect(minimapDrag).toEqual({
+      kind: 'minimap',
+      pointerId: 12,
+      startClientX: 120,
+      startClientY: 90,
+      startViewport: { x: 10, y: 20, scale: 1 },
+      minimapScale: 0.4,
+      moved: false,
+    });
+    expect(
+      updateMinimapDragMovement(minimapDrag, { x: 121, y: 90 }),
+    ).toBe(minimapDrag);
+    expect(updateMinimapDragMovement(minimapDrag, { x: 123, y: 90 })).toEqual({
+      ...minimapDrag,
+      moved: true,
+    });
+  });
+
+  it('creates generation frame drag state from mixed selection targets', () => {
+    const dialog: CanvasGenerationDialogState = {
+      id: 'dialog-1',
+      mode: 'generate',
+      prompt: '',
+      status: 'idle',
+      placeholder: {
+        x: 200,
+        y: 160,
+        width: 420,
+        height: 420,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+    };
+    const anotherDialog: CanvasGenerationDialogState = {
+      ...dialog,
+      id: 'dialog-2',
+      placeholder: {
+        ...dialog.placeholder!,
+        x: 680,
+        y: 160,
+      },
+    };
+    const layers = [createLayer({ id: 'layer-a', x: 40, y: 50 })];
+
+    expect(
+      createGenerationFrameSelectionStart({
+        dialog: anotherDialog,
+        layers,
+        generationDialogs: [dialog, anotherDialog],
+        selectedLayerIds: ['layer-a', getCanvasGenerationSelectionId('dialog-1')],
+        isMultiSelectGesture: true,
+        pointerId: 12,
+        pointer: { x: 360, y: 260 },
+        viewportScale: 1,
+      }),
+    ).toEqual({
+      selectedLayerIds: [
+        'layer-a',
+        getCanvasGenerationSelectionId('dialog-1'),
+        getCanvasGenerationSelectionId('dialog-2'),
+      ],
+      selectedLayerId: 'layer-a',
+      dragState: {
+        kind: 'generation-frame',
+        dialogId: 'dialog-2',
+        dialogIds: ['dialog-1', 'dialog-2'],
+        layerIds: ['layer-a'],
+        pointerId: 12,
+        startClientX: 360,
+        startClientY: 260,
+        startFrameX: 680,
+        startFrameY: 160,
+        startFrames: [
+          { id: 'dialog-1', x: 200, y: 160 },
+          { id: 'dialog-2', x: 680, y: 160 },
+        ],
+        startLayers: [{ id: 'layer-a', x: 40, y: 50 }],
+        startScale: 1,
+      },
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasStageInteractionModel.ts b/src/components/image-editor/ImageCanvasStageInteractionModel.ts
new file mode 100644
index 000000000..08ceb1a0d
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasStageInteractionModel.ts
@@ -0,0 +1,428 @@
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasViewport,
+  DragState,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import type { CanvasPoint } from './ImageCanvasInteractionModel';
+import {
+  firstSelectedLayerId,
+  getCanvasGenerationSelectionId,
+  getSelectedGenerationDialogIds,
+  getSelectedLayerIds,
+  resolvePointerSelection,
+} from './ImageCanvasSelectionModel';
+
+type PointerSource = {
+  button?: number;
+  buttons?: number;
+  clientX?: number;
+  clientY?: number;
+  pointerId?: number;
+  nativeEvent?: {
+    button?: number;
+    buttons?: number;
+    clientX?: number;
+    clientY?: number;
+    pointerId?: number;
+  };
+};
+
+type CanvasRectLike = {
+  left?: number;
+  top?: number;
+} | null | undefined;
+
+const CANVAS_GENERATION_DIALOG_MODES = new Set([
+  'generate',
+  'spec',
+  'character',
+  'icon',
+  'ui-design',
+  'character-animation',
+  'video',
+  'audio-sound-effect',
+  'audio-background-music',
+]);
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function hasCanvasGenerationDialogMode(
+  dialog: GenerateDialogState | null,
+): dialog is GenerateDialogState & {
+  mode: CanvasGenerationDialogState['mode'];
+} {
+  if (!dialog) {
+    return false;
+  }
+  return CANVAS_GENERATION_DIALOG_MODES.has(dialog.mode);
+}
+
+export function getPointerButton(event: PointerSource) {
+  const nativeButtons = Number(event.nativeEvent?.buttons);
+  if (Number.isFinite(nativeButtons) && (nativeButtons & 4) === 4) {
+    return 1;
+  }
+  const syntheticButtons = Number(event.buttons);
+  if (Number.isFinite(syntheticButtons) && (syntheticButtons & 4) === 4) {
+    return 1;
+  }
+  const syntheticButton = Number(event.button);
+  if (Number.isFinite(syntheticButton)) {
+    return syntheticButton;
+  }
+  const nativeButton = Number(event.nativeEvent?.button);
+  if (Number.isFinite(nativeButton)) {
+    return nativeButton;
+  }
+  return 0;
+}
+
+export function getPointerClient(event: PointerSource): CanvasPoint {
+  return {
+    x: isFiniteNumber(event.clientX)
+      ? event.clientX
+      : isFiniteNumber(event.nativeEvent?.clientX)
+        ? event.nativeEvent.clientX
+        : 0,
+    y: isFiniteNumber(event.clientY)
+      ? event.clientY
+      : isFiniteNumber(event.nativeEvent?.clientY)
+        ? event.nativeEvent.clientY
+        : 0,
+  };
+}
+
+export function getPointerId(event: PointerSource) {
+  return isFiniteNumber(event.pointerId)
+    ? event.pointerId
+    : isFiniteNumber(event.nativeEvent?.pointerId)
+      ? event.nativeEvent.pointerId
+      : -1;
+}
+
+export function getCanvasPointFromPointer({
+  pointer,
+  rect,
+}: {
+  pointer: CanvasPoint;
+  rect: CanvasRectLike;
+}): CanvasPoint {
+  return {
+    x: pointer.x - (rect?.left ?? 0),
+    y: pointer.y - (rect?.top ?? 0),
+  };
+}
+
+export function createCanvasMarqueeState({
+  pointerId,
+  pointer,
+  rect,
+}: {
+  pointerId: number;
+  pointer: CanvasPoint;
+  rect: CanvasRectLike;
+}): CanvasMarqueeState {
+  const startPoint = getCanvasPointFromPointer({ pointer, rect });
+  return {
+    pointerId,
+    startX: startPoint.x,
+    startY: startPoint.y,
+    currentX: startPoint.x,
+    currentY: startPoint.y,
+  };
+}
+
+export function createPanDragState({
+  pointerId,
+  pointer,
+  viewport,
+}: {
+  pointerId: number;
+  pointer: CanvasPoint;
+  viewport: CanvasViewport;
+}): Extract<DragState, { kind: 'pan' }> {
+  return {
+    kind: 'pan',
+    pointerId,
+    startClientX: pointer.x,
+    startClientY: pointer.y,
+    startViewport: viewport,
+  };
+}
+
+export function resolveLayerPointerSelection({
+  layerId,
+  selectedLayerIds,
+  isMultiSelectGesture,
+}: {
+  layerId: string;
+  selectedLayerIds: string[];
+  isMultiSelectGesture: boolean;
+}) {
+  return resolvePointerSelection({
+    targetId: layerId,
+    selectedIds: selectedLayerIds,
+    isMultiSelectGesture,
+  });
+}
+
+export function createLayerDragStart({
+  layer,
+  layers,
+  generationDialogs = [],
+  selectedLayerIds,
+  isMultiSelectGesture,
+  pointerId,
+  pointer,
+  viewportScale,
+}: {
+  layer: CanvasLayer;
+  layers: CanvasLayer[];
+  generationDialogs?: CanvasGenerationDialogState[];
+  selectedLayerIds: string[];
+  isMultiSelectGesture: boolean;
+  pointerId: number;
+  pointer: CanvasPoint;
+  viewportScale: number;
+}): {
+  selectedLayerIds: string[];
+  selectedLayerId: string | null;
+  dragState: Extract<DragState, { kind: 'layer' }>;
+} {
+  const nextSelectedLayerIds = resolveLayerPointerSelection({
+    layerId: layer.id,
+    selectedLayerIds,
+    isMultiSelectGesture,
+  });
+  const selectedCanvasLayerIds = getSelectedLayerIds(nextSelectedLayerIds);
+  const selectedGenerationDialogIds = getSelectedGenerationDialogIds(
+    nextSelectedLayerIds,
+  );
+  const dragLayerIds = selectedCanvasLayerIds.includes(layer.id)
+    ? selectedCanvasLayerIds
+    : [layer.id];
+  const startLayers = layers
+    .filter((currentLayer) => dragLayerIds.includes(currentLayer.id))
+    .map((currentLayer) => ({
+      id: currentLayer.id,
+      x: currentLayer.x,
+      y: currentLayer.y,
+    }));
+  const startGenerationFrames = generationDialogs
+    .filter(
+      (dialog) =>
+        selectedGenerationDialogIds.includes(dialog.id) && dialog.placeholder,
+    )
+    .map((dialog) => ({
+      id: dialog.id,
+      x: dialog.placeholder?.x ?? 0,
+      y: dialog.placeholder?.y ?? 0,
+    }));
+
+  return {
+    selectedLayerIds: nextSelectedLayerIds,
+    selectedLayerId: nextSelectedLayerIds.includes(layer.id)
+      ? layer.id
+      : firstSelectedLayerId(nextSelectedLayerIds),
+    dragState: {
+      kind: 'layer',
+      pointerId,
+      layerId: layer.id,
+      layerIds: dragLayerIds,
+      generationDialogIds: selectedGenerationDialogIds,
+      startClientX: pointer.x,
+      startClientY: pointer.y,
+      startLayerX: layer.x,
+      startLayerY: layer.y,
+      startLayers,
+      startGenerationFrames,
+      startScale: viewportScale,
+    },
+  };
+}
+
+export function updateGenerateDialogForLayerPointerDown(
+  dialog: GenerateDialogState | null,
+  _layerId: string,
+): GenerateDialogState | null {
+  if (!hasCanvasGenerationDialogMode(dialog)) {
+    return dialog;
+  }
+  return {
+    ...dialog,
+    composerOpen: false,
+  };
+}
+
+export function updateGenerateDialogForLayerClick(
+  dialog: GenerateDialogState | null,
+): GenerateDialogState | null {
+  if (!hasCanvasGenerationDialogMode(dialog)) {
+    return dialog;
+  }
+  return {
+    ...dialog,
+    composerOpen: false,
+  };
+}
+
+export function createGenerationFrameSelectionStart({
+  dialog,
+  layers,
+  generationDialogs,
+  selectedLayerIds,
+  isMultiSelectGesture,
+  pointerId,
+  pointer,
+  viewportScale,
+}: {
+  dialog: CanvasGenerationDialogState;
+  layers: CanvasLayer[];
+  generationDialogs: CanvasGenerationDialogState[];
+  selectedLayerIds: string[];
+  isMultiSelectGesture: boolean;
+  pointerId: number;
+  pointer: CanvasPoint;
+  viewportScale: number;
+}): {
+  selectedLayerIds: string[];
+  selectedLayerId: string | null;
+  dragState: Extract<DragState, { kind: 'generation-frame' }> | null;
+} {
+  const targetSelectionId = getCanvasGenerationSelectionId(dialog.id);
+  const nextSelectedLayerIds = resolvePointerSelection({
+    targetId: targetSelectionId,
+    selectedIds: selectedLayerIds,
+    isMultiSelectGesture,
+  });
+  const selectedGenerationDialogIds = getSelectedGenerationDialogIds(
+    nextSelectedLayerIds,
+  );
+  const selectedCanvasLayerIds = getSelectedLayerIds(nextSelectedLayerIds);
+  const dragDialogIds = selectedGenerationDialogIds.includes(dialog.id)
+    ? selectedGenerationDialogIds
+    : [dialog.id];
+  const startFrames = generationDialogs
+    .filter(
+      (currentDialog) =>
+        dragDialogIds.includes(currentDialog.id) && currentDialog.placeholder,
+    )
+    .map((currentDialog) => ({
+      id: currentDialog.id,
+      x: currentDialog.placeholder?.x ?? 0,
+      y: currentDialog.placeholder?.y ?? 0,
+    }));
+  const startLayers = layers
+    .filter((currentLayer) => selectedCanvasLayerIds.includes(currentLayer.id))
+    .map((currentLayer) => ({
+      id: currentLayer.id,
+      x: currentLayer.x,
+      y: currentLayer.y,
+    }));
+
+  return {
+    selectedLayerIds: nextSelectedLayerIds,
+    selectedLayerId: firstSelectedLayerId(nextSelectedLayerIds),
+    dragState: createGenerationFrameDragState({
+      dialog,
+      dialogIds: dragDialogIds,
+      layerIds: selectedCanvasLayerIds,
+      startFrames,
+      startLayers,
+      pointerId,
+      pointer,
+      viewportScale,
+    }),
+  };
+}
+
+export function createGenerationFrameDragState({
+  dialog,
+  dialogIds = [dialog.id],
+  layerIds = [],
+  startFrames,
+  startLayers = [],
+  pointerId,
+  pointer,
+  viewportScale,
+}: {
+  dialog: CanvasGenerationDialogState;
+  dialogIds?: string[];
+  layerIds?: string[];
+  startFrames?: Array<{ id: string; x: number; y: number }>;
+  startLayers?: Array<{ id: string; x: number; y: number }>;
+  pointerId: number;
+  pointer: CanvasPoint;
+  viewportScale: number;
+}): Extract<DragState, { kind: 'generation-frame' }> | null {
+  if (!dialog.placeholder) {
+    return null;
+  }
+  return {
+    kind: 'generation-frame',
+    dialogId: dialog.id,
+    dialogIds,
+    layerIds,
+    pointerId,
+    startClientX: pointer.x,
+    startClientY: pointer.y,
+    startFrameX: dialog.placeholder.x,
+    startFrameY: dialog.placeholder.y,
+    startFrames:
+      startFrames && startFrames.length
+        ? startFrames
+        : [
+            {
+              id: dialog.id,
+              x: dialog.placeholder.x,
+              y: dialog.placeholder.y,
+            },
+          ],
+    startLayers,
+    startScale: viewportScale,
+  };
+}
+
+export function createMinimapDragState({
+  pointerId,
+  pointer,
+  viewport,
+  minimapScale,
+}: {
+  pointerId: number;
+  pointer: CanvasPoint;
+  viewport: CanvasViewport;
+  minimapScale: number;
+}): Extract<DragState, { kind: 'minimap' }> {
+  return {
+    kind: 'minimap',
+    pointerId,
+    startClientX: pointer.x,
+    startClientY: pointer.y,
+    startViewport: { ...viewport },
+    minimapScale,
+    moved: false,
+  };
+}
+
+export function updateMinimapDragMovement(
+  dragState: Extract<DragState, { kind: 'minimap' }>,
+  pointer: CanvasPoint,
+): Extract<DragState, { kind: 'minimap' }> {
+  if (dragState.moved) {
+    return dragState;
+  }
+  const deltaX = pointer.x - dragState.startClientX;
+  const deltaY = pointer.y - dragState.startClientY;
+  return Math.hypot(deltaX, deltaY) >= 2
+    ? {
+        ...dragState,
+        moved: true,
+      }
+    : dragState;
+}
diff --git a/src/components/image-editor/ImageCanvasStageView.tsx b/src/components/image-editor/ImageCanvasStageView.tsx
new file mode 100644
index 000000000..74f7ef067
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasStageView.tsx
@@ -0,0 +1,368 @@
+import type {
+  CSSProperties,
+  DragEvent as ReactDragEvent,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+  RefObject,
+} from 'react';
+
+import { ImageCanvasBottomToolbarView } from './ImageCanvasBottomToolbarView';
+import { ImageCanvasContextMenusView } from './ImageCanvasContextMenusView';
+import type {
+  CanvasClipboard,
+  CanvasAssetKind,
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasTool,
+  CanvasViewport,
+  CropExpandPanelState,
+  CropExpandResizeHandle,
+  GenerateDialogState,
+  ImageContextMenuState,
+  SidebarPanel,
+  SnapGuide,
+} from './ImageCanvasEditorTypes';
+import type { StageMinimapModel } from './ImageCanvasInteractionModel';
+import { ImageCanvasPanelDockView } from './ImageCanvasPanelDockView';
+import { ImageCanvasSelectedLayerToolbarView } from './ImageCanvasSelectedLayerToolbarView';
+import { ImageCanvasWorldView } from './ImageCanvasWorldView';
+
+export type ImageCanvasStageViewProps = {
+  canvasViewportRef: RefObject<HTMLDivElement | null>;
+  specToolWrapRef: RefObject<HTMLSpanElement | null>;
+  musicToolWrapRef: RefObject<HTMLSpanElement | null>;
+  publicationToolWrapRef: RefObject<HTMLSpanElement | null>;
+  isPanning: boolean;
+  effectiveTool: CanvasTool;
+  canvasBackgroundColor: string;
+  canvasBackgroundHexValue: string;
+  viewport: CanvasViewport;
+  snapGuide: SnapGuide | null;
+  layers: CanvasLayer[];
+  selectedLayer: CanvasLayer | null;
+  selectedLayerIds: string[];
+  hoveredLayerId: string | null;
+  canvasMarquee: CanvasMarqueeState | null;
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  generateDialog: GenerateDialogState | null;
+  cropExpandPanel: CropExpandPanelState | null;
+  cropExpandSourceLayer: CanvasLayer | null;
+  generationComposerStyle: CSSProperties | null;
+  selectedToolbarStyle: CSSProperties | null;
+  uploadDropTarget: 'canvas' | 'assets' | null;
+  contextMenu: CanvasContextMenuState | null;
+  canvasClipboard: CanvasClipboard | null;
+  imageContextMenu: ImageContextMenuState | null;
+  imageContextMenuLayer: CanvasLayer | null;
+  contextShouldShowLayer: boolean;
+  contextShouldUnlockLayer: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  isZoomMenuOpen: boolean;
+  isBackgroundSettingsOpen: boolean;
+  activeSidebarPanel: SidebarPanel | null;
+  isMinimapOpen: boolean;
+  minimapModel: StageMinimapModel | null;
+  children?: ReactNode;
+  onCanvasPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onCanvasPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onCanvasPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onCanvasDragOver: (event: ReactDragEvent<HTMLDivElement>) => void;
+  onCanvasDragLeave: (event: ReactDragEvent<HTMLDivElement>) => void;
+  onCanvasDrop: (event: ReactDragEvent<HTMLDivElement>) => void;
+  onCanvasContextMenu: (event: ReactMouseEvent<HTMLDivElement>) => void;
+  onLayerPointerDown: (
+    event: ReactPointerEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onLayerClick: (
+    event: ReactMouseEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onSelectLayer: (layerId: string | null) => void;
+  onLayerContextMenu: (
+    event: ReactMouseEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onLayerMouseEnter: (layerId: string) => void;
+  onLayerMouseLeave: (layerId: string) => void;
+  onOpenLayerMetadata: (layer: CanvasLayer) => void;
+  onUpdateLayerAssetKind: (
+    layerId: string,
+    assetKind: CanvasAssetKind | null,
+  ) => void;
+  onGenerationFramePointerDown: (
+    event: ReactPointerEvent<HTMLDivElement>,
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  onActivateGenerationDialog: (dialog: CanvasGenerationDialogState) => void;
+  onCropExpandHandlePointerDown: (
+    event: ReactPointerEvent<HTMLButtonElement>,
+    handle: CropExpandResizeHandle,
+  ) => void;
+  onOpenQuickEditPanel: (layer: CanvasLayer) => void;
+  onOpenRedrawPanel: (layer: CanvasLayer) => void;
+  onOpenCropExpandPanel: (layer: CanvasLayer) => void;
+  onRemoveBackground: (layer: CanvasLayer) => void;
+  onExtractUiDesignAssets: (layer: CanvasLayer) => void;
+  onOpenCharacterAnimationPanel: (layer: CanvasLayer) => void;
+  onDownloadLayer: (layer: CanvasLayer) => void;
+  onPasteCanvasClipboard: (canvasPoint?: { x: number; y: number }) => void;
+  onCopyContextLayers: (options?: { cut?: boolean }) => void;
+  onDuplicateContextLayers: () => void;
+  onMoveContextLayers: (mode: 'up' | 'down' | 'top' | 'bottom') => void;
+  onGroupContextLayers: () => void;
+  onUngroupContextLayers: () => void;
+  onToggleContextLayerVisibility: () => void;
+  onToggleContextLayerLock: () => void;
+  onFlipContextLayers: (axis: 'x' | 'y') => void;
+  onExportContextLayer: () => void;
+  onDeleteContextLayers: () => void;
+  onDeleteLayerById: (layerId: string | null) => void;
+  onCloseContextMenu: () => void;
+  onCloseImageContextMenu: () => void;
+  onUpdateScaleFromCenter: (nextScale: number) => void;
+  onFitLayers: () => void;
+  onUndoCanvasChange: () => void;
+  onRedoCanvasChange: () => void;
+  onToggleZoomMenu: () => void;
+  onCloseZoomMenu: () => void;
+  onToggleBackgroundSettings: () => void;
+  onApplyCanvasBackgroundColor: (color: string) => void;
+  onCanvasBackgroundHexChange: (value: string) => void;
+  onToggleSidebarPanel: (panel: SidebarPanel) => void;
+  onToggleMinimap: () => void;
+  onMinimapPointerDown: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+  onSwitchTool: (tool: CanvasTool) => void;
+  onOpenToolOptions: (
+    tool: Extract<CanvasTool, 'music' | 'spec' | 'publication'>,
+  ) => void;
+  onCloseToolOptions: (
+    tool: Extract<CanvasTool, 'music' | 'spec' | 'publication'>,
+  ) => void;
+};
+
+export function ImageCanvasStageView({
+  canvasViewportRef,
+  specToolWrapRef,
+  musicToolWrapRef,
+  publicationToolWrapRef,
+  isPanning,
+  effectiveTool,
+  canvasBackgroundColor,
+  canvasBackgroundHexValue,
+  viewport,
+  snapGuide,
+  layers,
+  selectedLayer,
+  selectedLayerIds,
+  hoveredLayerId,
+  canvasMarquee,
+  canvasGenerationDialogs,
+  generateDialog,
+  cropExpandPanel,
+  cropExpandSourceLayer,
+  generationComposerStyle,
+  selectedToolbarStyle,
+  uploadDropTarget,
+  contextMenu,
+  canvasClipboard,
+  imageContextMenu,
+  imageContextMenuLayer,
+  contextShouldShowLayer,
+  contextShouldUnlockLayer,
+  canUndo,
+  canRedo,
+  isZoomMenuOpen,
+  isBackgroundSettingsOpen,
+  activeSidebarPanel,
+  isMinimapOpen,
+  minimapModel,
+  children,
+  onCanvasPointerDown,
+  onCanvasPointerMove,
+  onCanvasPointerUp,
+  onCanvasDragOver,
+  onCanvasDragLeave,
+  onCanvasDrop,
+  onCanvasContextMenu,
+  onLayerPointerDown,
+  onLayerClick,
+  onSelectLayer,
+  onLayerContextMenu,
+  onLayerMouseEnter,
+  onLayerMouseLeave,
+  onOpenLayerMetadata,
+  onUpdateLayerAssetKind,
+  onGenerationFramePointerDown,
+  onActivateGenerationDialog,
+  onCropExpandHandlePointerDown,
+  onOpenQuickEditPanel,
+  onOpenRedrawPanel,
+  onOpenCropExpandPanel,
+  onRemoveBackground,
+  onExtractUiDesignAssets,
+  onOpenCharacterAnimationPanel,
+  onDownloadLayer,
+  onPasteCanvasClipboard,
+  onCopyContextLayers,
+  onDuplicateContextLayers,
+  onMoveContextLayers,
+  onGroupContextLayers,
+  onUngroupContextLayers,
+  onToggleContextLayerVisibility,
+  onToggleContextLayerLock,
+  onFlipContextLayers,
+  onExportContextLayer,
+  onDeleteContextLayers,
+  onDeleteLayerById,
+  onCloseContextMenu,
+  onCloseImageContextMenu,
+  onUpdateScaleFromCenter,
+  onFitLayers,
+  onUndoCanvasChange,
+  onRedoCanvasChange,
+  onToggleZoomMenu,
+  onCloseZoomMenu,
+  onToggleBackgroundSettings,
+  onApplyCanvasBackgroundColor,
+  onCanvasBackgroundHexChange,
+  onToggleSidebarPanel,
+  onToggleMinimap,
+  onMinimapPointerDown,
+  onSwitchTool,
+  onOpenToolOptions,
+  onCloseToolOptions,
+}: ImageCanvasStageViewProps) {
+  return (
+    <div
+      ref={canvasViewportRef}
+      className={`image-canvas-editor__viewport ${isPanning ? 'image-canvas-editor__viewport--panning' : ''} image-canvas-editor__viewport--tool-${effectiveTool}`}
+      style={{ backgroundColor: canvasBackgroundColor }}
+      aria-label="画布工作区"
+      onPointerDown={onCanvasPointerDown}
+      onPointerMove={onCanvasPointerMove}
+      onPointerUp={onCanvasPointerUp}
+      onPointerCancel={onCanvasPointerUp}
+      onDragOver={onCanvasDragOver}
+      onDragLeave={onCanvasDragLeave}
+      onDrop={onCanvasDrop}
+      onContextMenu={onCanvasContextMenu}
+    >
+      {uploadDropTarget === 'canvas' ? (
+        <div
+          className="image-canvas-editor__upload-drop-overlay image-canvas-editor__upload-drop-overlay--canvas"
+          role="status"
+        >
+          <span>添加到画布</span>
+          <strong>松开即可添加</strong>
+        </div>
+      ) : null}
+      <ImageCanvasWorldView
+        viewport={viewport}
+        snapGuide={snapGuide}
+        layers={layers}
+        selectedLayerIds={selectedLayerIds}
+        hoveredLayerId={hoveredLayerId}
+        canvasMarquee={canvasMarquee}
+        canvasGenerationDialogs={canvasGenerationDialogs}
+        generateDialog={generateDialog}
+        cropExpandPanel={cropExpandPanel}
+        cropExpandSourceLayer={cropExpandSourceLayer}
+        generationComposerStyle={generationComposerStyle}
+        onLayerPointerDown={onLayerPointerDown}
+        onLayerClick={onLayerClick}
+        onSelectLayer={onSelectLayer}
+        onLayerContextMenu={onLayerContextMenu}
+        onLayerMouseEnter={onLayerMouseEnter}
+        onLayerMouseLeave={onLayerMouseLeave}
+        onOpenLayerMetadata={onOpenLayerMetadata}
+        onUpdateLayerAssetKind={onUpdateLayerAssetKind}
+        onGenerationFramePointerDown={onGenerationFramePointerDown}
+        onActivateGenerationDialog={onActivateGenerationDialog}
+        onCropExpandHandlePointerDown={onCropExpandHandlePointerDown}
+      />
+
+      <ImageCanvasSelectedLayerToolbarView
+        selectedLayer={selectedLayer}
+        selectedToolbarStyle={selectedToolbarStyle}
+        onOpenQuickEditPanel={onOpenQuickEditPanel}
+        onOpenRedrawPanel={onOpenRedrawPanel}
+        onOpenCropExpandPanel={onOpenCropExpandPanel}
+        onRemoveBackground={onRemoveBackground}
+        onExtractUiDesignAssets={onExtractUiDesignAssets}
+        onOpenCharacterAnimationPanel={onOpenCharacterAnimationPanel}
+        onDownloadLayer={onDownloadLayer}
+      />
+
+      <ImageCanvasContextMenusView
+        viewport={viewport}
+        contextMenu={contextMenu}
+        canvasClipboard={canvasClipboard}
+        imageContextMenu={imageContextMenu}
+        imageContextMenuLayer={imageContextMenuLayer}
+        contextShouldShowLayer={contextShouldShowLayer}
+        contextShouldUnlockLayer={contextShouldUnlockLayer}
+        onPasteCanvasClipboard={onPasteCanvasClipboard}
+        onCopyContextLayers={onCopyContextLayers}
+        onDuplicateContextLayers={onDuplicateContextLayers}
+        onMoveContextLayers={onMoveContextLayers}
+        onGroupContextLayers={onGroupContextLayers}
+        onUngroupContextLayers={onUngroupContextLayers}
+        onToggleContextLayerVisibility={onToggleContextLayerVisibility}
+        onToggleContextLayerLock={onToggleContextLayerLock}
+        onFlipContextLayers={onFlipContextLayers}
+        onExportContextLayer={onExportContextLayer}
+        onDeleteContextLayers={onDeleteContextLayers}
+        onDeleteLayerById={onDeleteLayerById}
+        onCloseContextMenu={onCloseContextMenu}
+        onCloseImageContextMenu={onCloseImageContextMenu}
+        onUpdateScaleFromCenter={onUpdateScaleFromCenter}
+        onFitLayers={onFitLayers}
+        onOpenQuickEditPanel={onOpenQuickEditPanel}
+        onOpenLayerMetadata={onOpenLayerMetadata}
+        onOpenCharacterAnimationPanel={onOpenCharacterAnimationPanel}
+      />
+
+      <ImageCanvasPanelDockView
+        viewport={viewport}
+        canvasBackgroundColor={canvasBackgroundColor}
+        canvasBackgroundHexValue={canvasBackgroundHexValue}
+        canUndo={canUndo}
+        canRedo={canRedo}
+        isZoomMenuOpen={isZoomMenuOpen}
+        isBackgroundSettingsOpen={isBackgroundSettingsOpen}
+        activeSidebarPanel={activeSidebarPanel}
+        isMinimapOpen={isMinimapOpen}
+        minimapModel={minimapModel}
+        onFitLayers={onFitLayers}
+        onUndoCanvasChange={onUndoCanvasChange}
+        onRedoCanvasChange={onRedoCanvasChange}
+        onUpdateScaleFromCenter={onUpdateScaleFromCenter}
+        onToggleZoomMenu={onToggleZoomMenu}
+        onCloseZoomMenu={onCloseZoomMenu}
+        onToggleBackgroundSettings={onToggleBackgroundSettings}
+        onApplyCanvasBackgroundColor={onApplyCanvasBackgroundColor}
+        onCanvasBackgroundHexChange={onCanvasBackgroundHexChange}
+        onToggleSidebarPanel={onToggleSidebarPanel}
+        onToggleMinimap={onToggleMinimap}
+        onMinimapPointerDown={onMinimapPointerDown}
+      />
+
+      <ImageCanvasBottomToolbarView
+        specToolWrapRef={specToolWrapRef}
+        musicToolWrapRef={musicToolWrapRef}
+        publicationToolWrapRef={publicationToolWrapRef}
+        effectiveTool={effectiveTool}
+        onSwitchTool={onSwitchTool}
+        onOpenToolOptions={onOpenToolOptions}
+        onCloseToolOptions={onCloseToolOptions}
+      />
+
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasTopbarView.test.tsx b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
new file mode 100644
index 000000000..75827629b
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
@@ -0,0 +1,147 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 180,
+    originalWidth: 320,
+    originalHeight: 180,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function renderTopbar(
+  overrides: Partial<
+    Parameters<typeof ImageCanvasTopbarView>[0]
+  > = {},
+) {
+  const props: Parameters<typeof ImageCanvasTopbarView>[0] = {
+    projectId: 'project-a',
+    projectTitle: '默认项目',
+    projectRenameValue: '默认项目',
+    isRenamingProject: false,
+    isProjectRenameSaving: false,
+    projectRenameError: null,
+    layers: [],
+    assetExportStatus: null,
+    isExportingAssets: false,
+    setProjectRenameValue: vi.fn(),
+    startProjectRename: vi.fn(),
+    cancelProjectRename: vi.fn(),
+    submitProjectRename: vi.fn(),
+    resetProjectRenameError: vi.fn(),
+    exportCanvasAssets: vi.fn(),
+    ...overrides,
+  };
+
+  render(<ImageCanvasTopbarView {...props} />);
+
+  return props;
+}
+
+describe('ImageCanvasTopbarView', () => {
+  it('shows the project title and project gallery link', () => {
+    const props = renderTopbar();
+
+    expect(screen.getByRole('heading', { name: '默认项目' })).toBeTruthy();
+    expect(
+      screen.getByRole('link', { name: '返回项目页面' }).getAttribute('href'),
+    ).toBe('/project');
+
+    fireEvent.click(screen.getByRole('button', { name: '编辑项目名称' }));
+
+    expect(props.startProjectRename).toHaveBeenCalledTimes(1);
+  });
+
+  it('submits, resets, and cancels project rename edits', () => {
+    const props = renderTopbar({
+      isRenamingProject: true,
+      projectRenameValue: '草稿项目',
+      projectRenameError: '项目名称不能为空',
+    });
+
+    const input = screen.getByLabelText('项目名称');
+    fireEvent.change(input, { target: { value: '新项目' } });
+    fireEvent.click(screen.getByRole('button', { name: '保存项目名称' }));
+
+    expect(props.setProjectRenameValue).toHaveBeenCalledWith('新项目');
+    expect(props.resetProjectRenameError).toHaveBeenCalledTimes(1);
+    expect(props.submitProjectRename).toHaveBeenCalledWith('project-a');
+    expect(screen.getByRole('alert').textContent).toBe('项目名称不能为空');
+
+    fireEvent.keyDown(input, { key: 'Escape' });
+
+    expect(props.cancelProjectRename).toHaveBeenCalledTimes(1);
+  });
+
+  it('exports only when canvas has exportable layers and shows export status', () => {
+    const exportCanvasAssets = vi.fn();
+    const { rerender } = render(
+      <ImageCanvasTopbarView
+        projectId="project-a"
+        projectTitle="默认项目"
+        projectRenameValue="默认项目"
+        isRenamingProject={false}
+        isProjectRenameSaving={false}
+        projectRenameError={null}
+        layers={[]}
+        assetExportStatus={null}
+        isExportingAssets={false}
+        setProjectRenameValue={vi.fn()}
+        startProjectRename={vi.fn()}
+        cancelProjectRename={vi.fn()}
+        submitProjectRename={vi.fn()}
+        resetProjectRenameError={vi.fn()}
+        exportCanvasAssets={exportCanvasAssets}
+      />,
+    );
+
+    expect(
+      (screen.getByRole('button', { name: '下载画布素材' }) as HTMLButtonElement)
+        .disabled,
+    ).toBe(true);
+
+    rerender(
+      <ImageCanvasTopbarView
+        projectId="project-a"
+        projectTitle="默认项目"
+        projectRenameValue="默认项目"
+        isRenamingProject={false}
+        isProjectRenameSaving={false}
+        projectRenameError={null}
+        layers={[createLayer()]}
+        assetExportStatus={{
+          tone: 'success',
+          message: '画布素材已导出',
+        }}
+        isExportingAssets={false}
+        setProjectRenameValue={vi.fn()}
+        startProjectRename={vi.fn()}
+        cancelProjectRename={vi.fn()}
+        submitProjectRename={vi.fn()}
+        resetProjectRenameError={vi.fn()}
+        exportCanvasAssets={exportCanvasAssets}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '下载画布素材' }));
+
+    expect(exportCanvasAssets).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('status').textContent).toBe('画布素材已导出');
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasTopbarView.tsx b/src/components/image-editor/ImageCanvasTopbarView.tsx
new file mode 100644
index 000000000..6fbf47dd4
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasTopbarView.tsx
@@ -0,0 +1,149 @@
+import { Check, ChevronLeft, Download, Pencil, X } from 'lucide-react';
+
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import type { AssetExportStatus } from './useImageCanvasAssetExportWorkflow';
+
+export type ImageCanvasTopbarViewProps = {
+  projectId: string | null;
+  projectTitle: string;
+  projectRenameValue: string;
+  isRenamingProject: boolean;
+  isProjectRenameSaving: boolean;
+  projectRenameError: string | null;
+  layers: CanvasLayer[];
+  assetExportStatus: AssetExportStatus | null;
+  isExportingAssets: boolean;
+  setProjectRenameValue: (value: string) => void;
+  startProjectRename: () => void;
+  cancelProjectRename: () => void;
+  submitProjectRename: (projectId: string | null) => void;
+  resetProjectRenameError: () => void;
+  exportCanvasAssets: () => void | Promise<void>;
+};
+
+export function ImageCanvasTopbarView({
+  projectId,
+  projectTitle,
+  projectRenameValue,
+  isRenamingProject,
+  isProjectRenameSaving,
+  projectRenameError,
+  layers,
+  assetExportStatus,
+  isExportingAssets,
+  setProjectRenameValue,
+  startProjectRename,
+  cancelProjectRename,
+  submitProjectRename,
+  resetProjectRenameError,
+  exportCanvasAssets,
+}: ImageCanvasTopbarViewProps) {
+  const hasExportableLayer = layers.some(
+    (layer) => layer.src.trim().length > 0,
+  );
+
+  return (
+    <div className="image-canvas-editor__topbar">
+      <a
+        className="image-canvas-editor__project-back-button"
+        href="/project"
+        aria-label="返回项目页面"
+        title="返回项目"
+      >
+        <ChevronLeft className="h-4 w-4" aria-hidden="true" />
+      </a>
+      <div className="image-canvas-editor__title-block">
+        {isRenamingProject ? (
+          <form
+            className="image-canvas-editor__project-title-form"
+            onSubmit={(event) => {
+              event.preventDefault();
+              submitProjectRename(projectId);
+            }}
+          >
+            <PlatformTextField
+              aria-label="项目名称"
+              value={projectRenameValue}
+              autoFocus
+              disabled={isProjectRenameSaving}
+              className="image-canvas-editor__project-title-input"
+              onChange={(event) => {
+                setProjectRenameValue(event.target.value);
+                resetProjectRenameError();
+              }}
+              onKeyDown={(event) => {
+                if (event.key === 'Escape') {
+                  event.preventDefault();
+                  cancelProjectRename();
+                }
+              }}
+            />
+            <EditorIconButton
+              type="submit"
+              label="保存项目名称"
+              title="保存"
+              icon={Check}
+              disabled={isProjectRenameSaving}
+            />
+            <EditorIconButton
+              label="取消修改项目名称"
+              title="取消"
+              icon={X}
+              disabled={isProjectRenameSaving}
+              onClick={cancelProjectRename}
+            />
+            {projectRenameError ? (
+              <span
+                className="image-canvas-editor__project-title-error"
+                role="alert"
+              >
+                {projectRenameError}
+              </span>
+            ) : null}
+          </form>
+        ) : (
+          <div className="image-canvas-editor__project-title-row">
+            <button
+              type="button"
+              className="image-canvas-editor__project-title-button"
+              onDoubleClick={startProjectRename}
+              aria-label={`编辑项目名称${projectTitle}`}
+            >
+              <h1>{projectTitle}</h1>
+            </button>
+            <EditorIconButton
+              className="image-canvas-editor__project-rename-button"
+              label="编辑项目名称"
+              title="编辑项目名称"
+              icon={Pencil}
+              onClick={startProjectRename}
+            />
+          </div>
+        )}
+        <span>画布</span>
+      </div>
+      <div className="image-canvas-editor__topbar-actions">
+        <EditorIconButton
+          label="下载画布素材"
+          title="下载画布素材"
+          icon={Download}
+          disabled={isExportingAssets || !hasExportableLayer}
+          onClick={() => void exportCanvasAssets()}
+        />
+        {assetExportStatus ? (
+          <PlatformStatusMessage
+            tone={assetExportStatus.tone}
+            surface="platform"
+            size="xs"
+            role={assetExportStatus.tone === 'error' ? 'alert' : 'status'}
+          >
+            {assetExportStatus.message}
+          </PlatformStatusMessage>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/image-editor/ImageCanvasUploadModel.test.ts b/src/components/image-editor/ImageCanvasUploadModel.test.ts
new file mode 100644
index 000000000..299201111
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasUploadModel.test.ts
@@ -0,0 +1,502 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasLayer,
+  EditorAssetFolder,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import {
+  applyGenerationReferenceUpload,
+  applyMeasuredUploadAssetSize,
+  applyPersistedUploadAsset,
+  applyUploadAssetCreateFailure,
+  applyUploadAssetCreatePending,
+  applyUploadAssetReadFailure,
+  applyUploadAssetReadSuccess,
+  bindUploadLayerToPersistedAsset,
+  createUploadCanvasLayer,
+  createUploadedGenerationReference,
+  createUploadingAssetPlaceholder,
+  expandUploadFolder,
+  resizeUploadCanvasLayerToImage,
+  resolveUploadFolderId,
+  setFailedGenerationIdle,
+} from './ImageCanvasUploadModel';
+
+function createFolder(
+  overrides: Partial<EditorAssetFolder> = {},
+): EditorAssetFolder {
+  return {
+    id: 'project',
+    label: '项目素材',
+    collapsed: false,
+    systemDefault: true,
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-upload-1',
+    resourceId: 'local-resource-upload-1',
+    title: '上传图片',
+    src: 'data:image/png;base64,upload',
+    x: -160,
+    y: -107.5,
+    width: 420,
+    height: 315,
+    originalWidth: 420,
+    originalHeight: 315,
+    zIndex: 11,
+    sourceType: 'uploaded',
+    sourceAssetId: 'upload-1',
+    ...overrides,
+  };
+}
+
+function createUploadingAsset(
+  overrides: Partial<ReturnType<typeof createUploadingAssetPlaceholder>> = {},
+) {
+  return {
+    ...createUploadingAssetPlaceholder({
+      uploadIndex: 1,
+      fileName: '上传图片.png',
+      folderId: 'project',
+    }),
+    ...overrides,
+  };
+}
+
+function createDialog(
+  overrides: Partial<GenerateDialogState> = {},
+): GenerateDialogState {
+  return {
+    mode: 'character',
+    prompt: '',
+    status: 'failed',
+    errorMessage: '旧错误',
+    ...overrides,
+  };
+}
+
+describe('ImageCanvasUploadModel', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('resolves upload folder ids with project fallback', () => {
+    const folders = [
+      createFolder(),
+      createFolder({ id: 'characters', label: '角色素材' }),
+    ];
+
+    expect(
+      resolveUploadFolderId({
+        assetFolders: folders,
+        requestedFolderId: 'characters',
+        activeUploadFolderId: 'project',
+      }),
+    ).toBe('characters');
+    expect(
+      resolveUploadFolderId({
+        assetFolders: folders,
+        requestedFolderId: 'missing',
+        activeUploadFolderId: 'characters',
+      }),
+    ).toBe('project');
+  });
+
+  it('creates uploading asset placeholders', () => {
+    expect(
+      createUploadingAssetPlaceholder({
+        uploadIndex: 7,
+        fileName: 'hero.png',
+        folderId: 'characters',
+      }),
+    ).toMatchObject({
+      id: 'upload-7',
+      label: 'hero.png',
+      src: '',
+      width: 420,
+      height: 315,
+      folderId: 'characters',
+      sourceKind: 'uploaded',
+      sourceType: 'uploaded',
+      persisted: false,
+      uploadStatus: 'uploading',
+      uploadProgress: 8,
+      uploadMessage: '准备上传',
+    });
+    expect(
+      createUploadingAssetPlaceholder({
+        uploadIndex: 8,
+        fileName: 'hero.png',
+        folderId: 'characters',
+        imageDimensions: { width: 1536, height: 1024 },
+      }),
+    ).toMatchObject({
+      id: 'upload-8',
+      width: 1536,
+      height: 1024,
+    });
+  });
+
+  it('opens the target upload folder without changing other folders', () => {
+    expect(
+      expandUploadFolder({
+        folders: [
+          createFolder({ id: 'project', collapsed: true }),
+          createFolder({ id: 'characters', label: '角色素材', collapsed: true }),
+        ],
+        folderId: 'characters',
+      }),
+    ).toEqual([
+      createFolder({ id: 'project', collapsed: true }),
+      createFolder({ id: 'characters', label: '角色素材', collapsed: false }),
+    ]);
+  });
+
+  it('applies upload asset lifecycle patches', () => {
+    const asset = createUploadingAsset();
+    const otherAsset = createUploadingAsset({
+      id: 'upload-other',
+      label: '其他图片.png',
+    });
+
+    expect(
+      applyUploadAssetReadSuccess({
+        assets: [asset, otherAsset],
+        uploadAssetId: asset.id,
+        imageSrc: 'data:image/png;base64,read',
+      }),
+    ).toMatchObject([
+      {
+        id: 'upload-1',
+        src: 'data:image/png;base64,read',
+        uploadProgress: 42,
+        uploadMessage: '读取素材',
+      },
+      { id: 'upload-other', label: '其他图片.png' },
+    ]);
+
+    expect(
+      applyUploadAssetCreatePending({
+        assets: [asset],
+        uploadAssetId: asset.id,
+      }),
+    ).toMatchObject([
+      {
+        id: 'upload-1',
+        uploadStatus: 'uploading',
+        uploadProgress: 68,
+        uploadMessage: '上传中',
+      },
+    ]);
+
+    expect(
+      applyUploadAssetReadFailure({
+        assets: [asset],
+        uploadAssetId: asset.id,
+      }),
+    ).toMatchObject([
+      {
+        id: 'upload-1',
+        uploadStatus: 'failed',
+        uploadProgress: 100,
+        uploadMessage: '读取失败',
+      },
+    ]);
+
+    expect(
+      applyUploadAssetCreateFailure({
+        assets: [asset],
+        uploadAssetId: asset.id,
+        message: '请先登录',
+      }),
+    ).toMatchObject([
+      {
+        id: 'upload-1',
+        uploadStatus: 'failed',
+        uploadProgress: 100,
+        uploadMessage: '请先登录',
+      },
+    ]);
+  });
+
+  it('replaces upload placeholders with persisted assets and clears upload state', () => {
+    expect(
+      applyPersistedUploadAsset({
+        assets: [createUploadingAsset()],
+        uploadAssetId: 'upload-1',
+        persistedAsset: {
+          assetId: 'asset-1',
+          folderId: 'characters',
+          label: '角色.png',
+          imageSrc: 'data:image/png;base64,persisted',
+          width: 1024,
+          height: 768,
+          objectKey: 'object-key',
+          assetObjectId: 'asset-object',
+        },
+      }),
+    ).toMatchObject([
+      {
+        id: 'asset-1',
+        label: '角色.png',
+        src: 'data:image/png;base64,persisted',
+        width: 1024,
+        height: 768,
+        folderId: 'characters',
+        sourceKind: 'uploaded',
+        sourceType: 'uploaded',
+        persisted: true,
+        objectKey: 'object-key',
+        assetObjectId: 'asset-object',
+        uploadStatus: undefined,
+        uploadProgress: undefined,
+        uploadMessage: undefined,
+      },
+    ]);
+  });
+
+  it('updates measured asset size after the browser loads the uploaded image', () => {
+    expect(
+      applyMeasuredUploadAssetSize({
+        assets: [createUploadingAsset()],
+        uploadAssetId: 'upload-1',
+        originalWidth: 1600,
+        originalHeight: 900,
+      }),
+    ).toMatchObject([
+      {
+        id: 'upload-1',
+        width: 1600,
+        height: 900,
+      },
+    ]);
+  });
+
+  it('binds uploaded canvas layers to persisted asset metadata', () => {
+    expect(
+      bindUploadLayerToPersistedAsset({
+        layers: [createLayer({ objectKey: 'local-object' })],
+        layerId: 'layer-upload-1',
+        persistedAsset: {
+          assetId: 'asset-1',
+          folderId: 'project',
+          label: '上传图片.png',
+          imageSrc: 'data:image/png;base64,persisted',
+          width: 420,
+          height: 315,
+          objectKey: 'object-key',
+          assetObjectId: 'asset-object',
+        },
+      }),
+    ).toMatchObject([
+      {
+        id: 'layer-upload-1',
+        src: 'data:image/png;base64,persisted',
+        sourceAssetId: 'asset-1',
+        objectKey: 'object-key',
+        assetObjectId: 'asset-object',
+      },
+    ]);
+  });
+
+  it('creates uploaded generation references with fallback labels', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-17T12:00:00.000Z'));
+
+    expect(
+      createUploadedGenerationReference({
+        idPrefix: 'upload-character-reference',
+        index: 2,
+        fileName: '',
+        fallbackLabel: '参考图3',
+        imageSrc: 'data:image/png;base64,ref',
+      }),
+    ).toEqual({
+      id: 'upload-character-reference-1781697600000-2',
+      label: '参考图3',
+      src: 'data:image/png;base64,ref',
+      mediaType: 'image',
+      mimeType: undefined,
+      sizeBytes: undefined,
+      durationSeconds: undefined,
+      objectKey: undefined,
+      assetObjectId: undefined,
+    });
+  });
+
+  it('resets failed generation dialogs when reference uploads are applied', () => {
+    expect(
+      setFailedGenerationIdle(
+        createDialog({ status: 'failed', errorMessage: '旧错误' }),
+      ),
+    ).toMatchObject({ status: 'idle', errorMessage: undefined });
+    expect(
+      setFailedGenerationIdle(createDialog({ status: 'generating' })),
+    ).toMatchObject({ status: 'generating', errorMessage: '旧错误' });
+  });
+
+  it('applies uploaded references to matching generation dialogs', () => {
+    const reference = {
+      id: 'ref-a',
+      label: '参考图',
+      src: 'data:image/png;base64,ref',
+    };
+
+    expect(
+      applyGenerationReferenceUpload({
+        dialog: createDialog({ mode: 'spec' }),
+        target: 'spec-reference',
+        references: [reference],
+      }),
+    ).toMatchObject({
+      mode: 'spec',
+      status: 'idle',
+      specReference: reference,
+      errorMessage: undefined,
+    });
+    expect(
+      applyGenerationReferenceUpload({
+        dialog: createDialog({ mode: 'character' }),
+        target: 'character-spec',
+        references: [reference],
+      }),
+    ).toMatchObject({
+      mode: 'character',
+      status: 'idle',
+      characterSpecReference: reference,
+    });
+    expect(
+      applyGenerationReferenceUpload({
+        dialog: createDialog({ mode: 'icon' }),
+        target: 'icon-spec',
+        references: [reference],
+      }),
+    ).toMatchObject({
+      mode: 'icon',
+      status: 'idle',
+      iconSpecReference: reference,
+    });
+  });
+
+  it('appends character reference uploads without changing unmatched dialogs', () => {
+    const previousReference = {
+      id: 'ref-old',
+      label: '旧参考图',
+      src: 'data:image/png;base64,old',
+    };
+    const nextReference = {
+      id: 'ref-new',
+      label: '新参考图',
+      src: 'data:image/png;base64,new',
+    };
+
+    expect(
+      applyGenerationReferenceUpload({
+        dialog: createDialog({
+          mode: 'character',
+          characterReferences: [previousReference],
+        }),
+        target: 'character-reference',
+        references: [nextReference],
+      }),
+    ).toMatchObject({
+      mode: 'character',
+      status: 'idle',
+      characterReferences: [previousReference, nextReference],
+    });
+    const iconDialog = createDialog({ mode: 'icon' });
+    expect(
+      applyGenerationReferenceUpload({
+        dialog: iconDialog,
+        target: 'character-reference',
+        references: [nextReference],
+      }),
+    ).toBe(iconDialog);
+  });
+
+  it('creates upload canvas layers centered on the target canvas point', () => {
+    const layer = createUploadCanvasLayer({
+      uploadIndex: 1,
+      fileName: '画布素材.png',
+      imageSrc: 'data:image/png;base64,canvas',
+      canvasPoint: { x: 110, y: 120 },
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+    });
+
+    expect(layer).toMatchObject({
+      id: 'layer-upload-1',
+      resourceId: 'local-resource-upload-1',
+      title: '画布素材.png',
+      x: -160,
+      y: -107.5,
+      width: 420,
+      height: 315,
+      originalWidth: 420,
+      originalHeight: 315,
+      zIndex: 11,
+      sourceAssetId: 'upload-1',
+    });
+  });
+
+  it('creates upload canvas layers with measured image dimensions', () => {
+    const layer = createUploadCanvasLayer({
+      uploadIndex: 1,
+      fileName: '画布素材.png',
+      imageSrc: 'data:image/png;base64,canvas',
+      imageDimensions: { width: 1536, height: 1024 },
+      canvasPoint: { x: 110, y: 120 },
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+    });
+
+    expect(layer).toMatchObject({
+      x: -718,
+      y: -462,
+      width: 1536,
+      height: 1024,
+      originalWidth: 1536,
+      originalHeight: 1024,
+    });
+  });
+
+  it('uses viewport center fallback for invalid upload points', () => {
+    const layer = createUploadCanvasLayer({
+      uploadIndex: 2,
+      fileName: '',
+      imageSrc: 'data:image/png;base64,canvas',
+      canvasPoint: { x: Number.NaN, y: Number.POSITIVE_INFINITY },
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+    });
+
+    expect(layer.title).toBe('上传图片');
+    expect(layer.x).toBe(10);
+    expect(layer.y).toBe(-7.5);
+  });
+
+  it('resizes upload canvas layers around the same canvas point', () => {
+    const resizedLayer = resizeUploadCanvasLayerToImage({
+      layer: createLayer(),
+      originalWidth: 1536,
+      originalHeight: 1024,
+      canvasPoint: { x: 110, y: 120 },
+      canvasSize: { width: 900, height: 640 },
+      viewport: { x: 10, y: 20, scale: 2 },
+    });
+
+    expect(resizedLayer).toMatchObject({
+      width: 1536,
+      height: 1024,
+      originalWidth: 1536,
+      originalHeight: 1024,
+      x: -718,
+      y: -462,
+    });
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasUploadModel.ts b/src/components/image-editor/ImageCanvasUploadModel.ts
new file mode 100644
index 000000000..c4d04c9c7
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasUploadModel.ts
@@ -0,0 +1,616 @@
+import { resolveLayerResolutionSize } from './ImageCanvasEditorModel';
+import type {
+  CharacterReferenceImage,
+  CanvasMediaType,
+  CanvasLayer,
+  CanvasViewport,
+  EditorAsset,
+  EditorAssetFolder,
+  GenerateDialogState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import { appendLimitedQuickEditReferences } from './ImageCanvasGenerationModel';
+
+type CanvasSize = { width: number; height: number };
+type CanvasPoint = { x: number; y: number };
+type UploadImageDimensions = { width: number; height: number } | null;
+type PersistedUploadAsset = {
+  assetId: string;
+  folderId: string;
+  label: string;
+  imageSrc: string;
+  mediaType?: CanvasMediaType;
+  width: number;
+  height: number;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  durationSeconds?: number | null;
+};
+type GenerationReferenceUploadTarget =
+  | 'character-reference'
+  | 'character-spec'
+  | 'generation-reference'
+  | 'quick-edit-reference'
+  | 'video-reference-image'
+  | 'video-reference-video'
+  | 'video-reference-audio'
+  | 'icon-spec'
+  | 'spec-reference'
+  | 'ui-design-icon-spec'
+  | 'publication-reference';
+
+const VIDEO_REFERENCE_LIMITS = {
+  image: 9,
+  video: 3,
+  audio: 3,
+} as const;
+
+export const UPLOAD_LAYER_FALLBACK_SIZE = {
+  width: 420,
+  height: 315,
+} as const;
+export const UPLOAD_VIDEO_FALLBACK_SIZE = {
+  width: 560,
+  height: 315,
+} as const;
+export const UPLOAD_AUDIO_FALLBACK_SIZE = {
+  width: 420,
+  height: 120,
+} as const;
+
+export function resolveUploadFallbackSize(mediaType: CanvasMediaType) {
+  if (mediaType === 'video') {
+    return UPLOAD_VIDEO_FALLBACK_SIZE;
+  }
+  if (mediaType === 'audio') {
+    return UPLOAD_AUDIO_FALLBACK_SIZE;
+  }
+  return UPLOAD_LAYER_FALLBACK_SIZE;
+}
+
+export function resolveUploadFolderId({
+  assetFolders,
+  requestedFolderId,
+  activeUploadFolderId,
+}: {
+  assetFolders: EditorAssetFolder[];
+  requestedFolderId?: string;
+  activeUploadFolderId: string;
+}) {
+  const targetFolderId = requestedFolderId ?? activeUploadFolderId;
+  return assetFolders.some((folder) => folder.id === targetFolderId)
+    ? targetFolderId
+    : 'project';
+}
+
+export function createUploadedGenerationReference({
+  idPrefix,
+  index,
+  fileName,
+  fallbackLabel,
+  imageSrc,
+  mediaType = 'image',
+  mimeType,
+  sizeBytes,
+  durationSeconds,
+  objectKey,
+  assetObjectId,
+  resourceId,
+  sourceAssetId,
+}: {
+  idPrefix: string;
+  index?: number;
+  fileName?: string;
+  fallbackLabel: string;
+  imageSrc: string;
+  mediaType?: CanvasMediaType;
+  mimeType?: string;
+  sizeBytes?: number;
+  durationSeconds?: number;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  resourceId?: string | null;
+  sourceAssetId?: string | null;
+}): CharacterReferenceImage {
+  return {
+    id:
+      typeof index === 'number'
+        ? `${idPrefix}-${Date.now()}-${index}`
+        : `${idPrefix}-${Date.now()}`,
+    label: fileName || fallbackLabel,
+    src: imageSrc,
+    mediaType,
+    mimeType,
+    sizeBytes,
+    durationSeconds,
+    objectKey,
+    assetObjectId,
+    resourceId,
+    sourceAssetId,
+  };
+}
+
+export function setFailedGenerationIdle(dialog: GenerateDialogState) {
+  return {
+    ...dialog,
+    status: dialog.status === 'failed' ? 'idle' : dialog.status,
+    errorMessage: dialog.status === 'failed' ? undefined : dialog.errorMessage,
+  };
+}
+
+export function applyGenerationReferenceUpload({
+  dialog,
+  target,
+  references,
+}: {
+  dialog: GenerateDialogState | null;
+  target: GenerationReferenceUploadTarget;
+  references: CharacterReferenceImage[];
+}): GenerateDialogState | null {
+  const firstReference = references[0];
+  if (!firstReference) {
+    return dialog;
+  }
+  if (target === 'spec-reference') {
+    return dialog?.mode === 'spec'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          specReference: firstReference,
+        }
+      : dialog;
+  }
+  if (target === 'character-spec') {
+    return dialog?.mode === 'character'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          characterSpecReference: firstReference,
+        }
+      : dialog;
+  }
+  if (target === 'icon-spec') {
+    return dialog?.mode === 'icon'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          iconSpecReference: firstReference,
+        }
+      : dialog;
+  }
+  if (target === 'ui-design-icon-spec') {
+    return dialog?.mode === 'ui-design'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          uiDesignSpecReference: firstReference,
+        }
+      : dialog;
+  }
+  if (target === 'publication-reference') {
+    return dialog?.mode === 'publication'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          publicationReferences: [
+            ...(dialog.publicationReferences ?? []),
+            ...references,
+          ],
+          composerOpen: true,
+        }
+      : dialog;
+  }
+  if (target === 'generation-reference') {
+    return dialog?.mode === 'generate' ||
+      dialog?.mode === 'video' ||
+      dialog?.mode === 'spec'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          generationReferences: [
+            ...(dialog.generationReferences ?? []),
+            ...references,
+          ],
+        }
+      : dialog;
+  }
+  if (
+    target === 'video-reference-image' ||
+    target === 'video-reference-video' ||
+    target === 'video-reference-audio'
+  ) {
+    const mediaType: CanvasMediaType =
+      target === 'video-reference-video'
+        ? 'video'
+        : target === 'video-reference-audio'
+          ? 'audio'
+          : 'image';
+    return dialog?.mode === 'video'
+      ? {
+          ...setFailedGenerationIdle(dialog),
+          generationReferences: appendLimitedVideoReferences(
+            dialog.generationReferences ?? [],
+            references,
+            mediaType,
+          ),
+          composerOpen: true,
+        }
+      : dialog;
+  }
+  return dialog?.mode === 'character'
+    ? {
+        ...setFailedGenerationIdle(dialog),
+        characterReferences: [
+          ...(dialog.characterReferences ?? []),
+          ...references,
+        ],
+      }
+    : dialog;
+}
+
+export function applyQuickEditReferenceUpload({
+  panel,
+  references,
+}: {
+  panel: QuickEditPanelState | null;
+  references: CharacterReferenceImage[];
+}): QuickEditPanelState | null {
+  if (!panel || panel.mode === 'redraw') {
+    return panel;
+  }
+  return {
+    ...panel,
+    status: panel.status === 'failed' ? 'idle' : panel.status,
+    errorMessage: panel.status === 'failed' ? undefined : panel.errorMessage,
+    quickEditReferences: appendLimitedQuickEditReferences(
+      panel.quickEditReferences,
+      references,
+    ),
+  };
+}
+
+function appendLimitedVideoReferences(
+  currentReferences: CharacterReferenceImage[],
+  nextReferences: CharacterReferenceImage[],
+  mediaType: CanvasMediaType,
+) {
+  const limit = VIDEO_REFERENCE_LIMITS[mediaType];
+  const currentCount = currentReferences.filter(
+    (reference) => (reference.mediaType ?? 'image') === mediaType,
+  ).length;
+  const remaining = Math.max(0, limit - currentCount);
+  return [
+    ...currentReferences,
+    ...nextReferences.slice(0, remaining).map((reference) => ({
+      ...reference,
+      mediaType,
+    })),
+  ];
+}
+
+export function createUploadingAssetPlaceholder({
+  uploadIndex,
+  fileName,
+  folderId,
+  mediaType = 'image',
+  imageDimensions,
+  durationSeconds,
+}: {
+  uploadIndex: number;
+  fileName?: string;
+  folderId: string;
+  mediaType?: CanvasMediaType;
+  imageDimensions?: UploadImageDimensions;
+  durationSeconds?: number;
+}): EditorAsset {
+  const fallbackSize = resolveUploadFallbackSize(mediaType);
+  const size =
+    mediaType === 'image' && imageDimensions
+      ? resolveLayerResolutionSize(
+          imageDimensions.width,
+          imageDimensions.height,
+          fallbackSize,
+        )
+      : fallbackSize;
+  return {
+    id: `upload-${uploadIndex}`,
+    label: fileName || (mediaType === 'audio' ? '上传音频' : mediaType === 'video' ? '上传视频' : '上传图片'),
+    src: '',
+    mediaType,
+    width: size.width,
+    height: size.height,
+    folderId,
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: false,
+    durationSeconds,
+    uploadStatus: 'uploading',
+    uploadProgress: 8,
+    uploadMessage: '准备上传',
+  };
+}
+
+export function expandUploadFolder({
+  folders,
+  folderId,
+}: {
+  folders: EditorAssetFolder[];
+  folderId: string;
+}) {
+  return folders.map((folder) =>
+    folder.id === folderId
+      ? {
+          ...folder,
+          collapsed: false,
+        }
+      : folder,
+  );
+}
+
+export function applyUploadAssetReadSuccess({
+  assets,
+  uploadAssetId,
+  imageSrc,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+  imageSrc: string;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          src: imageSrc,
+          uploadProgress: 42,
+          uploadMessage: '读取素材',
+        }
+      : asset,
+  );
+}
+
+export function applyUploadAssetReadFailure({
+  assets,
+  uploadAssetId,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          uploadStatus: 'failed' as const,
+          uploadProgress: 100,
+          uploadMessage: '读取失败',
+        }
+      : asset,
+  );
+}
+
+export function applyUploadAssetCreatePending({
+  assets,
+  uploadAssetId,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          uploadProgress: 68,
+          uploadMessage: '上传中',
+        }
+      : asset,
+  );
+}
+
+export function applyPersistedUploadAsset({
+  assets,
+  uploadAssetId,
+  persistedAsset,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+  persistedAsset: PersistedUploadAsset;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          id: persistedAsset.assetId,
+          folderId: persistedAsset.folderId,
+          label: persistedAsset.label,
+          src: persistedAsset.imageSrc,
+          mediaType: persistedAsset.mediaType ?? asset.mediaType,
+          width: persistedAsset.width,
+          height: persistedAsset.height,
+          objectKey: persistedAsset.objectKey ?? undefined,
+          assetObjectId: persistedAsset.assetObjectId ?? undefined,
+          durationSeconds: persistedAsset.durationSeconds ?? asset.durationSeconds,
+          persisted: true,
+          uploadStatus: undefined,
+          uploadProgress: undefined,
+          uploadMessage: undefined,
+        }
+      : asset,
+  );
+}
+
+export function applyUploadAssetCreateFailure({
+  assets,
+  uploadAssetId,
+  message,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+  message: string;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          uploadStatus: 'failed' as const,
+          uploadProgress: 100,
+          uploadMessage: message,
+        }
+      : asset,
+  );
+}
+
+export function applyMeasuredUploadAssetSize({
+  assets,
+  uploadAssetId,
+  originalWidth,
+  originalHeight,
+}: {
+  assets: EditorAsset[];
+  uploadAssetId: string;
+  originalWidth: number;
+  originalHeight: number;
+}) {
+  return assets.map((asset) =>
+    asset.id === uploadAssetId
+      ? {
+          ...asset,
+          width: originalWidth,
+          height: originalHeight,
+        }
+      : asset,
+  );
+}
+
+export function bindUploadLayerToPersistedAsset({
+  layers,
+  layerId,
+  persistedAsset,
+}: {
+  layers: CanvasLayer[];
+  layerId: string;
+  persistedAsset: PersistedUploadAsset;
+}) {
+  return layers.map((layer) =>
+    layer.id === layerId
+      ? {
+          ...layer,
+          src: persistedAsset.imageSrc || layer.src,
+          sourceAssetId: persistedAsset.assetId,
+          mediaType: persistedAsset.mediaType ?? layer.mediaType,
+          objectKey: persistedAsset.objectKey ?? layer.objectKey,
+          assetObjectId: persistedAsset.assetObjectId ?? layer.assetObjectId,
+          durationSeconds:
+            persistedAsset.durationSeconds ?? layer.durationSeconds,
+        }
+      : layer,
+  );
+}
+
+export function normalizeUploadScreenPoint({
+  canvasPoint,
+  canvasSize,
+}: {
+  canvasPoint?: CanvasPoint;
+  canvasSize: CanvasSize;
+}): CanvasPoint {
+  const fallbackScreenPoint = {
+    x: canvasSize.width > 0 ? canvasSize.width / 2 : 640,
+    y: canvasSize.height > 0 ? canvasSize.height / 2 : 360,
+  };
+  const screenPoint = canvasPoint ?? fallbackScreenPoint;
+  return {
+    x: Number.isFinite(screenPoint.x) ? screenPoint.x : fallbackScreenPoint.x,
+    y: Number.isFinite(screenPoint.y) ? screenPoint.y : fallbackScreenPoint.y,
+  };
+}
+
+export function createUploadCanvasLayer({
+  uploadIndex,
+  fileName,
+  imageSrc,
+  mediaType = 'image',
+  imageDimensions,
+  durationSeconds,
+  canvasPoint,
+  canvasSize,
+  viewport,
+}: {
+  uploadIndex: number;
+  fileName?: string;
+  imageSrc: string;
+  mediaType?: CanvasMediaType;
+  imageDimensions?: UploadImageDimensions;
+  durationSeconds?: number;
+  canvasPoint?: CanvasPoint;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): CanvasLayer {
+  const fallbackSize = resolveUploadFallbackSize(mediaType);
+  const layerSize =
+    mediaType === 'image' && imageDimensions
+      ? resolveLayerResolutionSize(
+          imageDimensions.width,
+          imageDimensions.height,
+          fallbackSize,
+        )
+      : fallbackSize;
+  const screenPoint = normalizeUploadScreenPoint({ canvasPoint, canvasSize });
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  const worldCenterX = (screenPoint.x - viewport.x) / safeScale;
+  const worldCenterY = (screenPoint.y - viewport.y) / safeScale;
+  return {
+    id: `layer-upload-${uploadIndex}`,
+    resourceId: `local-resource-upload-${uploadIndex}`,
+    title: fileName || (mediaType === 'audio' ? '上传音频' : mediaType === 'video' ? '上传视频' : '上传图片'),
+    src: imageSrc,
+    mediaType,
+    assetKind:
+      mediaType === 'video'
+        ? 'video'
+        : mediaType === 'audio'
+          ? 'sound-effect'
+          : undefined,
+    x: worldCenterX - layerSize.width / 2,
+    y: worldCenterY - layerSize.height / 2,
+    width: layerSize.width,
+    height: layerSize.height,
+    originalWidth: layerSize.width,
+    originalHeight: layerSize.height,
+    zIndex: uploadIndex + 10,
+    sourceType: 'uploaded',
+    sourceAssetId: `upload-${uploadIndex}`,
+    durationSeconds,
+  };
+}
+
+export function resizeUploadCanvasLayerToImage({
+  layer,
+  originalWidth,
+  originalHeight,
+  canvasPoint,
+  canvasSize,
+  viewport,
+}: {
+  layer: CanvasLayer;
+  originalWidth: number;
+  originalHeight: number;
+  canvasPoint?: CanvasPoint;
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+}): CanvasLayer {
+  const safeOriginalWidth =
+    originalWidth || UPLOAD_LAYER_FALLBACK_SIZE.width;
+  const safeOriginalHeight =
+    originalHeight || UPLOAD_LAYER_FALLBACK_SIZE.height;
+  const { width, height } = resolveLayerResolutionSize(
+    safeOriginalWidth,
+    safeOriginalHeight,
+    UPLOAD_LAYER_FALLBACK_SIZE,
+  );
+  const screenPoint = normalizeUploadScreenPoint({ canvasPoint, canvasSize });
+  const safeScale = viewport.scale > 0 ? viewport.scale : 1;
+  const worldCenterX = (screenPoint.x - viewport.x) / safeScale;
+  const worldCenterY = (screenPoint.y - viewport.y) / safeScale;
+  return {
+    ...layer,
+    width,
+    height,
+    originalWidth: safeOriginalWidth,
+    originalHeight: safeOriginalHeight,
+    x: worldCenterX - width / 2,
+    y: worldCenterY - height / 2,
+  };
+}
diff --git a/src/components/image-editor/ImageCanvasWorldView.test.tsx b/src/components/image-editor/ImageCanvasWorldView.test.tsx
new file mode 100644
index 000000000..3f2739fea
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasWorldView.test.tsx
@@ -0,0 +1,967 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasWorldView } from './ImageCanvasWorldView';
+
+const useResolvedAssetReadUrlMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../hooks/useResolvedAssetReadUrl', () => ({
+  useResolvedAssetReadUrl: useResolvedAssetReadUrlMock,
+}));
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-1',
+    resourceId: 'resource-1',
+    title: '角色主图',
+    src: 'data:image/png;base64,layer',
+    x: 120,
+    y: 160,
+    width: 320,
+    height: 240,
+    originalWidth: 640,
+    originalHeight: 480,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createGenerationDialog(
+  overrides: Partial<CanvasGenerationDialogState> = {},
+): CanvasGenerationDialogState {
+  return {
+    id: 'dialog-1',
+    mode: 'generate',
+    prompt: '生成一张图',
+    status: 'idle',
+    placeholder: {
+      x: 480,
+      y: 320,
+      width: 360,
+      height: 240,
+      originalWidth: 1024,
+      originalHeight: 768,
+    },
+    ...overrides,
+  };
+}
+
+function renderWorldView(
+  overrides: Partial<Parameters<typeof ImageCanvasWorldView>[0]> = {},
+) {
+  const props: Parameters<typeof ImageCanvasWorldView>[0] = {
+    viewport: { x: 10, y: 20, scale: 1.5 },
+    snapGuide: null,
+    layers: [createLayer()],
+    selectedLayerIds: [],
+    hoveredLayerId: null,
+    canvasMarquee: null,
+    canvasGenerationDialogs: [],
+    generateDialog: null,
+    cropExpandPanel: null,
+    cropExpandSourceLayer: null,
+    generationComposerStyle: null,
+    onLayerPointerDown: vi.fn(),
+    onLayerClick: vi.fn(),
+    onSelectLayer: vi.fn(),
+    onLayerContextMenu: vi.fn(),
+    onLayerMouseEnter: vi.fn(),
+    onLayerMouseLeave: vi.fn(),
+    onOpenLayerMetadata: vi.fn(),
+    onUpdateLayerAssetKind: vi.fn(),
+    onGenerationFramePointerDown: vi.fn(),
+    onActivateGenerationDialog: vi.fn(),
+    onCropExpandHandlePointerDown: vi.fn(),
+    ...overrides,
+  };
+
+  const result = render(<ImageCanvasWorldView {...props} />);
+
+  return { props, ...result };
+}
+
+describe('ImageCanvasWorldView', () => {
+  beforeEach(() => {
+    useResolvedAssetReadUrlMock.mockImplementation((source: string) => ({
+      resolvedUrl: source,
+      isResolving: false,
+      shouldResolve: false,
+    }));
+  });
+
+  it('renders visible layers and filters hidden layers', () => {
+    const visibleLayer = createLayer({ title: '可见图层', zIndex: 2 });
+    const hiddenLayer = createLayer({
+      id: 'layer-hidden',
+      resourceId: 'resource-hidden',
+      title: '隐藏图层',
+      hidden: true,
+    });
+
+    renderWorldView({
+      layers: [hiddenLayer, visibleLayer],
+      selectedLayerIds: [visibleLayer.id],
+      hoveredLayerId: visibleLayer.id,
+    });
+
+    const visibleButton = screen.getByRole('button', { name: '选择可见图层' });
+
+    expect(screen.queryByRole('button', { name: '选择隐藏图层' })).toBeNull();
+    expect(visibleButton.className).toContain(
+      'image-canvas-editor__layer--selected',
+    );
+    expect(visibleButton.className).toContain(
+      'image-canvas-editor__layer--hovered',
+    );
+    expect(visibleButton.className).not.toContain(
+      'image-canvas-editor__layer--generating',
+    );
+    expect(visibleButton.style.left).toBe('120px');
+    expect(visibleButton.style.top).toBe('160px');
+    expect(screen.getByText('640 x 480 px')).toBeTruthy();
+    expect(screen.queryByRole('status', { name: '' })).toBeNull();
+  });
+
+  it('resolves image layers from objectKey before falling back to src', () => {
+    useResolvedAssetReadUrlMock.mockImplementation(
+      (_source: string, options?: { objectKey?: string | null }) => ({
+      resolvedUrl:
+        options?.objectKey === 'generated-character-drafts/editor/uploaded.png'
+          ? 'https://oss.example.com/uploaded.png?signature=1'
+          : _source,
+      isResolving: false,
+      shouldResolve: true,
+      }),
+    );
+
+    renderWorldView({
+      layers: [
+        createLayer({
+          objectKey: 'generated-character-drafts/editor/uploaded.png',
+          src: '/generated-character-drafts/editor/stale.png',
+        }),
+      ],
+    });
+
+    expect(useResolvedAssetReadUrlMock).toHaveBeenCalledWith(
+      '/generated-character-drafts/editor/stale.png',
+      expect.objectContaining({
+        objectKey: 'generated-character-drafts/editor/uploaded.png',
+        refreshKey: 'resource-1',
+      }),
+    );
+    expect(screen.getByAltText('画布图片：角色主图').getAttribute('src')).toBe(
+      'https://oss.example.com/uploaded.png?signature=1',
+    );
+  });
+
+  it('forwards layer pointer, hover, context menu and metadata actions', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const { props } = renderWorldView({ layers: [layer] });
+
+    const layerButton = screen.getByRole('button', { name: '选择角色主图' });
+    const metadataButton = within(layerButton).getByRole('button', {
+      name: '查看角色主图图片信息',
+    });
+
+    fireEvent.pointerDown(layerButton);
+    fireEvent.click(layerButton);
+    fireEvent.contextMenu(layerButton);
+    fireEvent.mouseEnter(layerButton);
+    fireEvent.mouseLeave(layerButton);
+    fireEvent.click(metadataButton);
+
+    expect(props.onLayerPointerDown).toHaveBeenCalledWith(
+      expect.any(Object),
+      layer,
+    );
+    expect(props.onLayerClick).toHaveBeenCalledWith(expect.any(Object), layer);
+    expect(props.onLayerContextMenu).toHaveBeenCalledWith(
+      expect.any(Object),
+      layer,
+    );
+    expect(props.onLayerMouseEnter).toHaveBeenCalledWith(layer.id);
+    expect(props.onLayerMouseLeave).toHaveBeenCalledWith(layer.id);
+    expect(props.onOpenLayerMetadata).toHaveBeenCalledWith(layer);
+    expect(screen.getByText('角色')).toBeTruthy();
+  });
+
+  it('shows editable kind tags for tagged and untagged layers', () => {
+    const layer = createLayer({ assetKind: null });
+    renderWorldView({
+      layers: [
+        layer,
+        createLayer({
+          id: 'layer-character',
+          resourceId: 'resource-character',
+          title: '角色标签图层',
+          assetKind: 'character',
+        }),
+      ],
+    });
+
+    const layerButton = screen.getByRole('button', { name: '选择角色主图' });
+    const characterButton = screen.getByRole('button', {
+      name: '选择角色标签图层',
+    });
+
+    expect(within(layerButton).getByText('未知')).toBeTruthy();
+    expect(within(characterButton).getByText('角色')).toBeTruthy();
+  });
+
+  it('renders snap guides, marquee and floating generation status', () => {
+    renderWorldView({
+      snapGuide: { vertical: 288, horizontal: 344 },
+      canvasMarquee: {
+        pointerId: 1,
+        startX: 40,
+        startY: 50,
+        currentX: 190,
+        currentY: 230,
+      },
+      generateDialog: {
+        id: 'dialog-active',
+        mode: 'generate',
+        prompt: '生成中',
+        status: 'generating',
+      },
+      generationComposerStyle: { left: 12, top: 24 },
+    });
+
+    expect(
+      screen.getByTestId('image-canvas-editor-snap-guide-vertical').style.left,
+    ).toBe('288px');
+    expect(
+      screen.getByTestId('image-canvas-editor-snap-guide-horizontal').style.top,
+    ).toBe('344px');
+    expect(screen.getByText('生成中')).toBeTruthy();
+
+    const world = document.querySelector('.image-canvas-editor__world');
+    const marquee = world?.querySelector('.image-canvas-editor__canvas-marquee');
+
+    expect(world?.getAttribute('style')).toContain(
+      'transform: translate(10px, 20px) scale(1.5)',
+    );
+    expect((marquee as HTMLElement | null)?.style.width).toBe('100px');
+    expect((marquee as HTMLElement | null)?.style.height).toBe('120px');
+  });
+
+  it('renders generation placeholders and forwards frame actions', () => {
+    const dialog = createGenerationDialog({
+      mode: 'icon',
+      status: 'generating',
+    });
+    const { props } = renderWorldView({
+      canvasGenerationDialogs: [
+        dialog,
+        createGenerationDialog({
+          id: 'dialog-without-placeholder',
+          placeholder: undefined,
+        }),
+      ],
+      generateDialog: dialog,
+    });
+
+    const frame = screen.getByRole('button', { name: '图标素材生成占位图' });
+
+    expect(frame.className).toContain(
+      'image-canvas-editor__generation-frame--focused',
+    );
+    expect(within(frame).getByText('Icon Generator')).toBeTruthy();
+    expect(within(frame).getByText('图标')).toBeTruthy();
+    expect(within(frame).getByText('1024 x 768')).toBeTruthy();
+    expect(within(frame).getByRole('status').textContent).toBe('生成中');
+
+    fireEvent.pointerDown(frame);
+    fireEvent.doubleClick(frame);
+
+    expect(props.onGenerationFramePointerDown).toHaveBeenCalledWith(
+      expect.any(Object),
+      dialog,
+    );
+    expect(props.onActivateGenerationDialog).toHaveBeenCalledWith(dialog);
+    expect(
+      within(frame).queryByRole('button', { name: '删除图标素材生成占位图' }),
+    ).toBeNull();
+    expect(screen.queryByText('dialog-without-placeholder')).toBeNull();
+  });
+
+  it('renders crop-expand frame handles and forwards drag actions', () => {
+    const layer = createLayer();
+    const { props } = renderWorldView({
+      layers: [layer],
+      cropExpandSourceLayer: layer,
+      cropExpandPanel: {
+        sourceLayerId: layer.id,
+        frame: { x: 100, y: 140, width: 360, height: 300 },
+        ratio: 'free',
+        status: 'idle',
+      },
+    });
+
+    const frame = screen.getByRole('group', { name: '裁扩边界' });
+    const rightHandle = within(frame).getByRole('button', {
+      name: '拖拽裁扩右边',
+    });
+
+    expect(frame.style.left).toBe('100px');
+    expect(frame.style.width).toBe('360px');
+
+    fireEvent.pointerDown(rightHandle);
+
+    expect(props.onCropExpandHandlePointerDown).toHaveBeenCalledWith(
+      expect.any(Object),
+      'right',
+    );
+  });
+
+  it('hides idle placeholder chrome after blur and restores it when focused', () => {
+    const dialog = createGenerationDialog({
+      id: 'dialog-idle',
+      mode: 'generate',
+      status: 'idle',
+    });
+
+    const { rerender, props } = renderWorldView({
+      canvasGenerationDialogs: [dialog],
+      generateDialog: null,
+    });
+
+    const blurredFrame = screen.getByRole('button', { name: '图像生成占位图' });
+    expect(blurredFrame.className).not.toContain(
+      'image-canvas-editor__generation-frame--focused',
+    );
+    expect(within(blurredFrame).queryByText('Image Generator')).toBeNull();
+    expect(within(blurredFrame).queryByText('1024 x 768')).toBeNull();
+
+    rerender(<ImageCanvasWorldView {...props} generateDialog={dialog} />);
+
+    const focusedFrame = screen.getByRole('button', { name: '图像生成占位图' });
+    expect(focusedFrame.className).toContain(
+      'image-canvas-editor__generation-frame--focused',
+    );
+    expect(within(focusedFrame).getByText('Image Generator')).toBeTruthy();
+    expect(within(focusedFrame).getByText('1024 x 768')).toBeTruthy();
+  });
+
+  it.each([
+    {
+      mode: 'character',
+      ariaLabel: '角色生成占位图',
+      generatorLabel: 'Character Generator',
+      badgeLabel: '角色',
+      frameClassName: 'image-canvas-editor__generation-frame--character',
+      iconClassName: 'lucide-user-round',
+    },
+    {
+      mode: 'character-animation',
+      ariaLabel: '角色动作生成占位图',
+      generatorLabel: 'Action Generator',
+      badgeLabel: '动作',
+      frameClassName:
+        'image-canvas-editor__generation-frame--character-animation',
+      iconClassName: 'lucide-person-standing',
+    },
+    {
+      mode: 'publication',
+      ariaLabel: '宣发素材生成占位图',
+      generatorLabel: 'Home Image Generator',
+      badgeLabel: '宣发',
+      frameClassName: 'image-canvas-editor__generation-frame--publication',
+      iconClassName: 'lucide-megaphone',
+    },
+    {
+      mode: 'spec',
+      ariaLabel: '规范生成占位图',
+      generatorLabel: 'Spec Generator',
+      badgeLabel: '规范',
+      frameClassName: 'image-canvas-editor__generation-frame--spec',
+      iconClassName: 'lucide-clipboard-list',
+    },
+    {
+      mode: 'ui-design',
+      ariaLabel: 'UI设计图生成占位图',
+      generatorLabel: 'UI Design Generator',
+      badgeLabel: 'UI设计',
+      frameClassName: 'image-canvas-editor__generation-frame--ui-design',
+      iconClassName: 'lucide-app-window',
+    },
+    {
+      mode: 'quick-edit',
+      ariaLabel: '快速编辑生成占位图',
+      generatorLabel: 'Quick Edit Generator',
+      badgeLabel: '快编',
+      frameClassName: 'image-canvas-editor__generation-frame--quick-edit',
+      iconClassName: 'lucide-sparkles',
+    },
+    {
+      mode: 'video',
+      ariaLabel: '视频生成占位图',
+      generatorLabel: 'Video Generator',
+      badgeLabel: '视频',
+      frameClassName: 'image-canvas-editor__generation-frame--video',
+      iconClassName: 'lucide-clapperboard',
+    },
+    {
+      mode: 'audio-sound-effect',
+      ariaLabel: '音效生成占位图',
+      generatorLabel: 'Sound Generator',
+      badgeLabel: '音效',
+      frameClassName:
+        'image-canvas-editor__generation-frame--audio-sound-effect',
+      iconClassName: 'lucide-volume-2',
+    },
+    {
+      mode: 'audio-background-music',
+      ariaLabel: '背景音乐生成占位图',
+      generatorLabel: 'Music Generator',
+      badgeLabel: '背景音乐',
+      frameClassName:
+        'image-canvas-editor__generation-frame--audio-background-music',
+      iconClassName: 'lucide-music',
+    },
+  ])(
+    'renders $mode generation placeholder with its own icon and badge',
+    ({ mode, ariaLabel, generatorLabel, badgeLabel, frameClassName, iconClassName }) => {
+      const dialog = createGenerationDialog({
+        id: `dialog-${mode}`,
+        mode: mode as CanvasGenerationDialogState['mode'],
+      });
+
+      renderWorldView({
+        canvasGenerationDialogs: [dialog],
+        generateDialog: dialog as GenerateDialogState,
+      });
+
+      const frame = screen.getByRole('button', { name: ariaLabel });
+      const generatorLabelNode = within(frame).getByText(
+        generatorLabel,
+      ) as HTMLElement;
+      expect(frame.className).toContain(frameClassName);
+      expect(generatorLabelNode).toBeTruthy();
+      expect(
+        generatorLabelNode.querySelector('svg')?.getAttribute('class'),
+      ).toContain(iconClassName);
+      expect(within(frame).getByText(badgeLabel)).toBeTruthy();
+      expect(
+        frame
+          .querySelector('.image-canvas-editor__generation-frame-icon svg')
+          ?.getAttribute('class'),
+      ).toContain(iconClassName);
+    },
+  );
+
+  it.each([
+    {
+      mode: 'character',
+      ariaLabel: '角色生成占位图',
+      generatorLabel: 'Character Generator',
+      badgeLabel: '角色',
+    },
+    {
+      mode: 'character-animation',
+      ariaLabel: '角色动作生成占位图',
+      generatorLabel: 'Action Generator',
+      badgeLabel: '动作',
+    },
+    {
+      mode: 'publication',
+      ariaLabel: '宣发素材生成占位图',
+      generatorLabel: 'Home Image Generator',
+      badgeLabel: '宣发',
+    },
+    {
+      mode: 'video',
+      ariaLabel: '视频生成占位图',
+      generatorLabel: 'Video Generator',
+      badgeLabel: '视频',
+    },
+    {
+      mode: 'audio-sound-effect',
+      ariaLabel: '音效生成占位图',
+      generatorLabel: 'Sound Generator',
+      badgeLabel: '音效',
+    },
+    {
+      mode: 'audio-background-music',
+      ariaLabel: '背景音乐生成占位图',
+      generatorLabel: 'Music Generator',
+      badgeLabel: '背景音乐',
+    },
+  ])(
+    'keeps $mode generation title size and badge readable when zoomed out',
+    ({ mode, ariaLabel, generatorLabel, badgeLabel }) => {
+      const dialog = createGenerationDialog({
+        id: `dialog-zoom-${mode}`,
+        mode: mode as CanvasGenerationDialogState['mode'],
+      });
+
+      renderWorldView({
+        viewport: { x: 0, y: 0, scale: 0.25 },
+        canvasGenerationDialogs: [dialog],
+        generateDialog: dialog as GenerateDialogState,
+      });
+
+      const frame = screen.getByRole('button', { name: ariaLabel });
+      const inverseScale = '4';
+
+      expect(
+        (within(frame).getByText(generatorLabel) as HTMLElement).style.getPropertyValue(
+          '--image-canvas-editor-inverse-scale',
+        ),
+      ).toBe(inverseScale);
+      expect(
+        mode === 'audio-sound-effect' || mode === 'audio-background-music'
+          ? within(frame).queryByText('1024 x 768')
+          : (
+              within(frame).getByText('1024 x 768') as HTMLElement
+            ).style.getPropertyValue('--image-canvas-editor-inverse-scale'),
+      ).toBe(
+        mode === 'audio-sound-effect' || mode === 'audio-background-music'
+          ? null
+          : inverseScale,
+      );
+      expect(
+        (within(frame).getByText(badgeLabel) as HTMLElement).style.getPropertyValue(
+          '--image-canvas-editor-inverse-scale',
+        ),
+      ).toBe(inverseScale);
+    },
+  );
+
+  it.each([
+    {
+      mode: 'character',
+      ariaLabel: '角色生成占位图',
+      generatorLabel: 'Character Generator',
+      badgeLabel: '角色',
+    },
+    {
+      mode: 'character-animation',
+      ariaLabel: '角色动作生成占位图',
+      generatorLabel: 'Action Generator',
+      badgeLabel: '动作',
+    },
+    {
+      mode: 'publication',
+      ariaLabel: '宣发素材生成占位图',
+      generatorLabel: 'Home Image Generator',
+      badgeLabel: '宣发',
+    },
+    {
+      mode: 'video',
+      ariaLabel: '视频生成占位图',
+      generatorLabel: 'Video Generator',
+      badgeLabel: '视频',
+    },
+    {
+      mode: 'audio-sound-effect',
+      ariaLabel: '音效生成占位图',
+      generatorLabel: 'Sound Generator',
+      badgeLabel: '音效',
+    },
+    {
+      mode: 'audio-background-music',
+      ariaLabel: '背景音乐生成占位图',
+      generatorLabel: 'Music Generator',
+      badgeLabel: '背景音乐',
+    },
+  ])(
+    'keeps $mode placeholder icon and badge visible after blur without helper chrome',
+    ({ mode, ariaLabel, generatorLabel, badgeLabel }) => {
+      const dialog = createGenerationDialog({
+        id: `dialog-blurred-${mode}`,
+        mode: mode as CanvasGenerationDialogState['mode'],
+        status: 'idle',
+      });
+
+      renderWorldView({
+        generateDialog: null,
+        canvasGenerationDialogs: [dialog],
+      });
+
+      const frame = screen.getByRole('button', { name: ariaLabel });
+      expect(frame.className).not.toContain(
+        'image-canvas-editor__generation-frame--focused',
+      );
+      expect(within(frame).queryByText(generatorLabel)).toBeNull();
+      expect(within(frame).queryByText('1024 x 768')).toBeNull();
+      expect(within(frame).getByText(badgeLabel)).toBeTruthy();
+      expect(
+        frame.querySelector('.image-canvas-editor__generation-frame-icon svg'),
+      ).toBeTruthy();
+    },
+  );
+
+  it('keeps layer and generation chrome readable when the canvas is zoomed out', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const dialog = createGenerationDialog({ id: 'dialog-focused' });
+
+    renderWorldView({
+      viewport: { x: 0, y: 0, scale: 0.25 },
+      layers: [layer],
+      hoveredLayerId: layer.id,
+      canvasGenerationDialogs: [dialog],
+      generateDialog: dialog,
+    });
+
+    const layerButton = screen.getByRole('button', { name: '选择角色主图' });
+    const frame = screen.getByRole('button', { name: '图像生成占位图' });
+    const inverseScale = '4';
+
+    expect(
+      (within(layerButton).getByText('角色') as HTMLElement).style.getPropertyValue(
+        '--image-canvas-editor-inverse-scale',
+      ),
+    ).toBe(inverseScale);
+    expect(
+      (within(layerButton).getByText('640 x 480 px') as HTMLElement).style.getPropertyValue(
+        '--image-canvas-editor-inverse-scale',
+      ),
+    ).toBe(inverseScale);
+    expect(
+      within(layerButton)
+        .getByRole('button', { name: '查看角色主图图片信息' })
+        .style.getPropertyValue('--image-canvas-editor-inverse-scale'),
+    ).toBe(inverseScale);
+    expect(
+      (within(frame).getByText('Image Generator') as HTMLElement).style.getPropertyValue(
+        '--image-canvas-editor-inverse-scale',
+      ),
+    ).toBe(inverseScale);
+    expect(
+      (within(frame).getByText('1024 x 768') as HTMLElement).style.getPropertyValue(
+        '--image-canvas-editor-inverse-scale',
+      ),
+    ).toBe(inverseScale);
+  });
+
+  it('keeps blank generation placeholder icons readable when the canvas is zoomed out', () => {
+    const dialog = createGenerationDialog({ id: 'dialog-icon-scale' });
+
+    renderWorldView({
+      viewport: { x: 0, y: 0, scale: 0.25 },
+      canvasGenerationDialogs: [dialog],
+      generateDialog: null,
+    });
+
+    const frame = screen.getByRole('button', { name: '图像生成占位图' });
+    expect(
+      (frame.querySelector('.image-canvas-editor__generation-frame-icon') as HTMLElement)
+        .style.getPropertyValue('--image-canvas-editor-inverse-scale'),
+    ).toBe('4');
+  });
+
+  it('uses a plain information icon for metadata corner actions', () => {
+    const layer = createLayer();
+    const { props } = renderWorldView({ layers: [layer] });
+
+    const metadataButton = screen.getByRole('button', {
+      name: '查看角色主图图片信息',
+    });
+
+    expect(metadataButton.querySelector('svg')?.getAttribute('class')).toContain(
+      'lucide-info',
+    );
+  });
+
+  it('renders audio layers with an audio control card instead of an image', () => {
+    const layer = createLayer({
+      title: '游戏音效',
+      src: '/generated-character-drafts/editor-audios/sfx.mp3',
+      mediaType: 'audio',
+      assetKind: 'sound-effect',
+      width: 420,
+      height: 120,
+      originalWidth: 420,
+      originalHeight: 120,
+    });
+
+    const { props } = renderWorldView({ layers: [layer] });
+
+    const layerButton = screen.getByRole('button', { name: '选择游戏音效' });
+    const audio = within(layerButton).getByLabelText('画布音频：游戏音效');
+    const preview = layerButton.querySelector(
+      '.image-canvas-editor__media-preview--audio',
+    );
+    expect(audio.tagName.toLowerCase()).toBe('audio');
+    expect(preview?.className).toContain(
+      'image-canvas-editor__media-preview--variant-',
+    );
+    expect(audio.hasAttribute('controls')).toBe(false);
+    expect(within(layerButton).queryByAltText('画布图片：游戏音效')).toBeNull();
+    expect(within(layerButton).getByText('音效')).toBeTruthy();
+    expect(within(layerButton).queryByText(/时长/u)).toBeNull();
+    expect(
+      within(layerButton).getAllByRole('button', { name: /播放|暂停/u }),
+    ).toHaveLength(1);
+    expect(
+      within(layerButton).getByRole('button', { name: '播放游戏音效' })
+        .querySelector('svg')
+        ?.getAttribute('class'),
+    ).toContain('lucide-volume-2');
+    expect(
+      layerButton
+        .querySelector('.image-canvas-editor__audio-card-controls')
+        ?.className.includes(
+          'image-canvas-editor__audio-card-controls--integrated',
+        ),
+    ).toBe(true);
+    expect(
+      layerButton
+        .querySelector('.image-canvas-editor__audio-card')
+        ?.className.includes(
+          'image-canvas-editor__audio-card--controls-visible',
+        ),
+    ).toBe(false);
+    expect(
+      within(layerButton).getByLabelText('调整游戏音效播放进度'),
+    ).toBeTruthy();
+    expect(within(layerButton).getByLabelText('静音游戏音效')).toBeTruthy();
+    expect(within(layerButton).getByLabelText('调整游戏音效音量')).toBeTruthy();
+    expect(
+      within(layerButton).queryByText('420 x 120 px'),
+    ).toBeNull();
+  });
+
+  it('keeps audio controls interactive and switches icon, play and pause states', () => {
+    const layer = createLayer({
+      title: '游戏背景音乐',
+      src: 'data:audio/mpeg;base64,audio',
+      mediaType: 'audio',
+      assetKind: 'background-music',
+      width: 420,
+      height: 120,
+      originalWidth: 420,
+      originalHeight: 120,
+      prompt: '紧张的地下城循环音乐',
+      durationSeconds: 75,
+    });
+    const { props, rerender } = renderWorldView({
+      layers: [layer],
+      selectedLayerIds: [layer.id],
+    });
+
+    const layerButton = screen.getByRole('button', { name: '选择游戏背景音乐' });
+    const audio = within(layerButton).getByLabelText('画布音频：游戏背景音乐');
+    const playbackButton = within(layerButton).getByRole('button', {
+      name: '播放游戏背景音乐',
+    });
+
+    expect(within(layerButton).getByText('紧张的地下城循环音乐')).toBeTruthy();
+    expect(within(layerButton).queryByText(/时长/u)).toBeNull();
+    expect(
+      playbackButton.querySelector('svg')?.getAttribute('class'),
+    ).toContain('lucide-music');
+
+    rerender(
+      <ImageCanvasWorldView
+        {...props}
+        layers={[layer]}
+        hoveredLayerId={layer.id}
+        selectedLayerIds={[layer.id]}
+      />,
+    );
+    const hoveredLayerButton = screen.getByRole('button', {
+      name: '选择游戏背景音乐',
+    });
+    expect(
+      hoveredLayerButton
+        .querySelector('.image-canvas-editor__audio-card')
+        ?.className.includes(
+          'image-canvas-editor__audio-card--controls-visible',
+        ),
+    ).toBe(true);
+    expect(
+      within(hoveredLayerButton)
+        .getByRole('button', { name: '播放游戏背景音乐' })
+        .querySelector('svg')
+        ?.getAttribute('class'),
+    ).toContain('lucide-play');
+
+    const hoveredAudio = within(hoveredLayerButton).getByLabelText(
+      '画布音频：游戏背景音乐',
+    );
+    fireEvent.play(hoveredAudio);
+    expect(
+      within(hoveredLayerButton)
+        .getByRole('button', { name: '暂停游戏背景音乐' })
+        .querySelector('svg')
+        ?.getAttribute('class'),
+    ).toContain('lucide-pause');
+
+    fireEvent.pointerDown(hoveredAudio);
+    fireEvent.click(hoveredAudio);
+
+    expect(props.onLayerPointerDown).not.toHaveBeenCalled();
+    expect(props.onLayerClick).not.toHaveBeenCalled();
+  });
+
+  it('places layer type labels to the left of the information action', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const { props } = renderWorldView({ layers: [layer] });
+
+    const layerButton = screen.getByRole('button', { name: '选择角色主图' });
+    const badge = within(layerButton).getByText('角色');
+    const metadataButton = within(layerButton).getByRole('button', {
+      name: '查看角色主图图片信息',
+    });
+
+    expect(badge.className).toContain(
+      'image-canvas-editor__kind-badge--beside-info',
+    );
+    expect(metadataButton.className).not.toContain(
+      'image-canvas-editor__metadata-corner--beside-kind',
+    );
+  });
+
+  it('keeps the layer type menu scrollable and closes it when clicking outside', () => {
+    const layer = createLayer({ assetKind: 'character' });
+    const documentWheel = vi.fn();
+    document.addEventListener('wheel', documentWheel);
+
+    try {
+      renderWorldView({ layers: [layer] });
+
+      fireEvent.click(screen.getByRole('button', { name: '素材标签：角色' }));
+
+      const menu = screen.getByRole('menu', { name: '选择素材标签' });
+      fireEvent.wheel(menu, { deltaY: 120 });
+
+      expect(documentWheel).not.toHaveBeenCalled();
+      expect(screen.getByRole('menu', { name: '选择素材标签' })).toBeTruthy();
+
+      fireEvent.pointerDown(menu);
+      expect(screen.getByRole('menu', { name: '选择素材标签' })).toBeTruthy();
+
+      fireEvent.pointerDown(document.body);
+      expect(
+        screen.queryByRole('menu', { name: '选择素材标签' }),
+      ).toBeNull();
+    } finally {
+      document.removeEventListener('wheel', documentWheel);
+    }
+  });
+
+  it('hides resolution and duration text for focused audio generation frames', () => {
+    const dialog = createGenerationDialog({
+      id: 'dialog-audio',
+      mode: 'audio-sound-effect',
+    });
+
+    renderWorldView({
+      canvasGenerationDialogs: [dialog],
+      generateDialog: dialog,
+    });
+
+    const frame = screen.getByRole('button', { name: '音效生成占位图' });
+    expect(within(frame).queryByText('时长 --:--')).toBeNull();
+    expect(within(frame).queryByText('1024 x 768')).toBeNull();
+  });
+
+  it('renders video layers with a playable video element instead of an image', () => {
+    useResolvedAssetReadUrlMock.mockImplementation((source: string) => ({
+      resolvedUrl:
+        source === '/generated-character-drafts/editor-videos/video-7.mp4'
+          ? 'https://oss.example.com/video-7.mp4?signature=1'
+          : source,
+      isResolving: false,
+      shouldResolve: true,
+    }));
+    const layer = createLayer({
+      title: '生成视频 7',
+      src: '/generated-character-drafts/editor-videos/video-7.mp4',
+      mediaType: 'video',
+      assetKind: 'video',
+      width: 854,
+      height: 480,
+      originalWidth: 854,
+      originalHeight: 480,
+    });
+
+    const { props } = renderWorldView({ layers: [layer] });
+
+    const layerButton = screen.getByRole('button', { name: '选择生成视频 7' });
+    const video = within(layerButton).getByLabelText('画布视频：生成视频 7');
+    fireEvent.pointerDown(video);
+    fireEvent.click(video);
+
+    expect(video.tagName.toLowerCase()).toBe('video');
+    expect(video.getAttribute('src')).toBe(
+      'https://oss.example.com/video-7.mp4?signature=1',
+    );
+    expect(video.hasAttribute('controls')).toBe(true);
+    expect(video.hasAttribute('playsinline')).toBe(true);
+    expect(video.getAttribute('preload')).toBe('metadata');
+    expect(
+      layerButton.querySelector('.image-canvas-editor__media-preview--video')
+        ?.className,
+    ).toContain('image-canvas-editor__media-preview--variant-');
+    expect(within(layerButton).queryByAltText('画布视频：生成视频 7')).toBeNull();
+    expect(within(layerButton).getByText('视频')).toBeTruthy();
+    expect(props.onLayerPointerDown).toHaveBeenCalledWith(
+      expect.any(Object),
+      layer,
+    );
+    expect(props.onLayerClick).not.toHaveBeenCalled();
+  });
+
+  it('keeps private video src empty while signed url resolution fails', () => {
+    useResolvedAssetReadUrlMock.mockImplementation(() => ({
+      resolvedUrl: '',
+      isResolving: false,
+      shouldResolve: true,
+    }));
+    const layer = createLayer({
+      title: '私有视频',
+      src: '/generated-character-drafts/editor-videos/private.mp4',
+      mediaType: 'video',
+      objectKey: 'generated-character-drafts/editor-videos/private.mp4',
+      assetKind: 'video',
+    });
+
+    renderWorldView({ layers: [layer] });
+
+    const layerButton = screen.getByRole('button', { name: '选择私有视频' });
+    const video = within(layerButton).getByLabelText('画布视频：私有视频');
+    expect(video.hasAttribute('src')).toBe(false);
+    expect(useResolvedAssetReadUrlMock).toHaveBeenCalledWith(
+      '/generated-character-drafts/editor-videos/private.mp4',
+      expect.objectContaining({
+        objectKey: 'generated-character-drafts/editor-videos/private.mp4',
+      }),
+    );
+  });
+
+  it('keeps saved generator placeholders hidden after a result layer exists', () => {
+    renderWorldView({
+      layers: [createLayer({ id: 'layer-generated', title: '生成图片' })],
+      canvasGenerationDialogs: [
+        createGenerationDialog({
+          generatedLayerId: 'layer-generated',
+          placeholder: {
+            x: 80,
+            y: 90,
+            width: 420,
+            height: 420,
+            originalWidth: 2048,
+            originalHeight: 2048,
+          },
+        }),
+      ],
+    });
+
+    expect(screen.getByRole('button', { name: '选择生成图片' })).toBeTruthy();
+    expect(
+      screen.queryByRole('button', { name: '图像生成占位图' }),
+    ).toBeNull();
+  });
+});
diff --git a/src/components/image-editor/ImageCanvasWorldView.tsx b/src/components/image-editor/ImageCanvasWorldView.tsx
new file mode 100644
index 000000000..709a0465f
--- /dev/null
+++ b/src/components/image-editor/ImageCanvasWorldView.tsx
@@ -0,0 +1,1061 @@
+import {
+  AppWindow,
+  Clapperboard,
+  ClipboardList,
+  Grid2X2,
+  ImageIcon,
+  Info,
+  Megaphone,
+  Music,
+  Pause,
+  Play,
+  PersonStanding,
+  Sparkles,
+  UserRound,
+  Volume2,
+  VolumeX,
+} from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type {
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from 'react';
+
+import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformIconButton } from '../common/PlatformIconButton';
+import { PlatformPillBadge } from '../common/PlatformPillBadge';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { CANVAS_WORLD_SIZE } from './ImageCanvasEditorModel';
+import type {
+  CanvasAssetKind,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasViewport,
+  CropExpandPanelState,
+  CropExpandResizeHandle,
+  GenerateDialogState,
+  SnapGuide,
+} from './ImageCanvasEditorTypes';
+import {
+  getGenerationFrameAriaLabel,
+  getGenerationFrameLabel,
+} from './ImageCanvasGenerationModel';
+import {
+  getCanvasMediaPreviewClassName,
+  getCanvasMediaPreviewMarker,
+} from './ImageCanvasMediaModel';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+
+function getGenerationPlaceholderMeta(dialog: CanvasGenerationDialogState) {
+  switch (dialog.mode) {
+    case 'character':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--character',
+        badgeClassName: 'character',
+        badgeLabel: '角色',
+        icon: <UserRound className="h-8 w-8" />,
+        labelIcon: <UserRound className="h-4 w-4" />,
+      };
+    case 'character-animation':
+      return {
+        frameClassName:
+          'image-canvas-editor__generation-frame--character-animation',
+        badgeClassName: 'character-animation',
+        badgeLabel: '动作',
+        icon: <PersonStanding className="h-8 w-8" />,
+        labelIcon: <PersonStanding className="h-4 w-4" />,
+      };
+    case 'spec':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--spec',
+        badgeClassName: 'spec',
+        badgeLabel: '规范',
+        icon: <ClipboardList className="h-8 w-8" />,
+        labelIcon: <ClipboardList className="h-4 w-4" />,
+      };
+    case 'icon':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--icon',
+        badgeClassName: 'icon',
+        badgeLabel: '图标',
+        icon: <Grid2X2 className="h-8 w-8" />,
+        labelIcon: <Grid2X2 className="h-4 w-4" />,
+      };
+    case 'ui-design':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--ui-design',
+        badgeClassName: 'ui-design',
+        badgeLabel: 'UI设计',
+        icon: <AppWindow className="h-8 w-8" />,
+        labelIcon: <AppWindow className="h-4 w-4" />,
+      };
+    case 'quick-edit':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--quick-edit',
+        badgeClassName: 'quick-edit',
+        badgeLabel: '快编',
+        icon: <Sparkles className="h-8 w-8" />,
+        labelIcon: <Sparkles className="h-4 w-4" />,
+      };
+    case 'publication':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--publication',
+        badgeClassName: 'publication',
+        badgeLabel: '宣发',
+        icon: <Megaphone className="h-8 w-8" />,
+        labelIcon: <Megaphone className="h-4 w-4" />,
+      };
+    case 'video':
+      return {
+        frameClassName: 'image-canvas-editor__generation-frame--video',
+        badgeClassName: 'video',
+        badgeLabel: '视频',
+        icon: <Clapperboard className="h-8 w-8" />,
+        labelIcon: <Clapperboard className="h-4 w-4" />,
+      };
+    case 'audio-sound-effect':
+      return {
+        frameClassName:
+          'image-canvas-editor__generation-frame--audio-sound-effect',
+        badgeClassName: 'sound-effect',
+        badgeLabel: '音效',
+        icon: <Volume2 className="h-8 w-8" />,
+        labelIcon: <Volume2 className="h-4 w-4" />,
+      };
+    case 'audio-background-music':
+      return {
+        frameClassName:
+          'image-canvas-editor__generation-frame--audio-background-music',
+        badgeClassName: 'background-music',
+        badgeLabel: '背景音乐',
+        icon: <Music className="h-8 w-8" />,
+        labelIcon: <Music className="h-4 w-4" />,
+      };
+    default:
+      return {
+        frameClassName: '',
+        badgeClassName: null,
+        badgeLabel: null,
+        icon: <ImageIcon className="h-8 w-8" />,
+        labelIcon: <ImageIcon className="h-4 w-4" />,
+      };
+  }
+}
+
+function getInverseViewportScale(viewport: CanvasViewport) {
+  if (!Number.isFinite(viewport.scale) || viewport.scale <= 0) {
+    return 1;
+  }
+  return 1 / viewport.scale;
+}
+
+function buildInverseScaleStyle(
+  inverseScale: number,
+): CSSProperties & Record<string, string> {
+  return {
+    '--image-canvas-editor-inverse-scale': String(inverseScale),
+    '--image-canvas-editor-corner-offset': `calc(0.35rem * ${inverseScale})`,
+    '--image-canvas-editor-kind-offset': `calc(0.38rem * ${inverseScale})`,
+    '--image-canvas-editor-beside-kind-offset': `calc(1.95rem * ${inverseScale})`,
+    '--image-canvas-editor-frame-label-offset': `calc(-1.35rem * ${inverseScale})`,
+  };
+}
+
+const CANVAS_ASSET_KIND_TAG_OPTIONS: Array<{
+  value: CanvasAssetKind | null;
+  label: string;
+  className: string;
+}> = [
+  { value: null, label: '未知', className: 'unknown' },
+  { value: 'spec', label: '规范', className: 'spec' },
+  { value: 'character', label: '角色', className: 'character' },
+  {
+    value: 'character-animation',
+    label: '动作',
+    className: 'character-animation',
+  },
+  { value: 'icon', label: '图标', className: 'icon' },
+  { value: 'icon-spritesheet', label: '图集', className: 'icon-spritesheet' },
+  { value: 'icon-spec', label: '图标规范', className: 'icon-spec' },
+  {
+    value: 'publication-material',
+    label: '宣发素材',
+    className: 'publication-material',
+  },
+  { value: 'ui-design', label: 'UI设计', className: 'ui-design' },
+  { value: 'video', label: '视频', className: 'video' },
+  { value: 'sound-effect', label: '音效', className: 'sound-effect' },
+  {
+    value: 'background-music',
+    label: '背景音乐',
+    className: 'background-music',
+  },
+];
+
+const UNKNOWN_ASSET_KIND_TAG_OPTION = CANVAS_ASSET_KIND_TAG_OPTIONS[0] as {
+  value: null;
+  label: string;
+  className: string;
+};
+
+function getLayerKindTagMeta(layer: CanvasLayer) {
+  const knownKind = layer.assetKind
+    ? CANVAS_ASSET_KIND_TAG_OPTIONS.find(
+        (option) => option.value === layer.assetKind,
+      )
+    : null;
+  if (knownKind) {
+    return knownKind;
+  }
+  return UNKNOWN_ASSET_KIND_TAG_OPTION;
+}
+
+export type ImageCanvasWorldViewProps = {
+  viewport: CanvasViewport;
+  snapGuide: SnapGuide | null;
+  layers: CanvasLayer[];
+  selectedLayerIds: string[];
+  hoveredLayerId: string | null;
+  canvasMarquee: CanvasMarqueeState | null;
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  generateDialog: GenerateDialogState | null;
+  cropExpandPanel: CropExpandPanelState | null;
+  cropExpandSourceLayer: CanvasLayer | null;
+  generationComposerStyle: CSSProperties | null;
+  onLayerPointerDown: (
+    event: ReactPointerEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onLayerClick: (
+    event: ReactMouseEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onSelectLayer: (layerId: string | null) => void;
+  onLayerContextMenu: (
+    event: ReactMouseEvent<HTMLElement>,
+    layer: CanvasLayer,
+  ) => void;
+  onLayerMouseEnter: (layerId: string) => void;
+  onLayerMouseLeave: (layerId: string) => void;
+  onOpenLayerMetadata: (layer: CanvasLayer) => void;
+  onUpdateLayerAssetKind: (
+    layerId: string,
+    assetKind: CanvasAssetKind | null,
+  ) => void;
+  onGenerationFramePointerDown: (
+    event: ReactPointerEvent<HTMLDivElement>,
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  onActivateGenerationDialog: (dialog: CanvasGenerationDialogState) => void;
+  onCropExpandHandlePointerDown: (
+    event: ReactPointerEvent<HTMLButtonElement>,
+    handle: CropExpandResizeHandle,
+  ) => void;
+};
+
+const CROP_EXPAND_HANDLES: Array<{
+  value: CropExpandResizeHandle;
+  label: string;
+}> = [
+  { value: 'top-left', label: '左上角' },
+  { value: 'top', label: '上边' },
+  { value: 'top-right', label: '右上角' },
+  { value: 'right', label: '右边' },
+  { value: 'bottom-right', label: '右下角' },
+  { value: 'bottom', label: '下边' },
+  { value: 'bottom-left', label: '左下角' },
+  { value: 'left', label: '左边' },
+];
+
+function stopMediaEventPropagation(
+  event: ReactMouseEvent<HTMLElement> | ReactPointerEvent<HTMLElement>,
+) {
+  event.stopPropagation();
+}
+
+function selectMediaLayerWithoutDrag(
+  event: ReactPointerEvent<HTMLElement>,
+  onSelectLayer: () => void,
+) {
+  event.stopPropagation();
+  onSelectLayer();
+}
+
+function handleLayerKeyboardActivation(
+  event: ReactKeyboardEvent<HTMLElement>,
+) {
+  if (event.key !== 'Enter' && event.key !== ' ') {
+    return;
+  }
+  event.preventDefault();
+  event.currentTarget.click();
+}
+
+function handleLayerTagKeyboardActivation(
+  event: ReactKeyboardEvent<HTMLElement>,
+) {
+  if (event.key !== 'Enter' && event.key !== ' ') {
+    return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  event.currentTarget.click();
+}
+
+function stopMediaControlKeyPropagation(
+  event: ReactKeyboardEvent<HTMLElement>,
+) {
+  if (event.key === 'Backspace' || event.key === 'Delete') {
+    return;
+  }
+  event.stopPropagation();
+}
+
+function getLayerMetricLabel(layer: CanvasLayer) {
+  return `${Math.round(layer.originalWidth)} x ${Math.round(
+    layer.originalHeight,
+  )} px`;
+}
+
+function getAudioLayerIcon(layer: CanvasLayer) {
+  return layer.assetKind === 'background-music' ? (
+    <Music className="h-8 w-8" aria-hidden="true" />
+  ) : (
+    <Volume2 className="h-8 w-8" aria-hidden="true" />
+  );
+}
+
+function getAudioDurationSeconds(durationSeconds: CanvasLayer['durationSeconds']) {
+  return typeof durationSeconds === 'number' &&
+    Number.isFinite(durationSeconds) &&
+    durationSeconds > 0
+    ? durationSeconds
+    : 0;
+}
+
+function formatAudioControlTime(seconds: number) {
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return '0:00';
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.floor(seconds % 60)
+    .toString()
+    .padStart(2, '0');
+  return `${minutes}:${remainingSeconds}`;
+}
+
+function ImageCanvasAudioLayerCard({
+  layer,
+  isHovered,
+  onSelectLayer,
+}: {
+  layer: CanvasLayer;
+  isHovered: boolean;
+  onSelectLayer: () => void;
+}) {
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const previewClassName = getCanvasMediaPreviewClassName(
+    getCanvasMediaPreviewMarker(layer),
+  );
+  const [isPlaying, setIsPlaying] = useState(false);
+  const { resolvedUrl } = useResolvedAssetReadUrl(layer.src, {
+    objectKey: layer.objectKey,
+    refreshKey: layer.taskId ?? layer.resourceId,
+  });
+  const prompt = layer.prompt?.trim();
+  const fallbackDuration = getAudioDurationSeconds(layer.durationSeconds);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(fallbackDuration);
+  const [volume, setVolume] = useState(1);
+  const [isMuted, setIsMuted] = useState(false);
+  const showPlaybackButton = isPlaying || isHovered;
+  const controlDuration = duration > 0 ? duration : fallbackDuration;
+  const safeCurrentTime =
+    controlDuration > 0 ? Math.min(currentTime, controlDuration) : 0;
+
+  useEffect(() => {
+    setIsPlaying(false);
+    setCurrentTime(0);
+    setDuration(fallbackDuration);
+  }, [fallbackDuration, layer.src]);
+
+  const togglePlayback = async () => {
+    const audio = audioRef.current;
+    if (!audio) {
+      return;
+    }
+    if (isPlaying) {
+      audio.pause();
+      return;
+    }
+    try {
+      await audio.play();
+    } catch {
+      setIsPlaying(false);
+    }
+  };
+
+  const handleSeekChange = (nextValue: string) => {
+    const nextTime = Number(nextValue);
+    if (!Number.isFinite(nextTime)) {
+      return;
+    }
+    const clampedTime =
+      controlDuration > 0
+        ? Math.min(Math.max(nextTime, 0), controlDuration)
+        : Math.max(nextTime, 0);
+    if (audioRef.current) {
+      audioRef.current.currentTime = clampedTime;
+    }
+    setCurrentTime(clampedTime);
+  };
+
+  const handleVolumeChange = (nextValue: string) => {
+    const nextVolume = Number(nextValue);
+    if (!Number.isFinite(nextVolume)) {
+      return;
+    }
+    const clampedVolume = Math.min(Math.max(nextVolume, 0), 1);
+    if (audioRef.current) {
+      audioRef.current.volume = clampedVolume;
+      audioRef.current.muted = clampedVolume === 0;
+    }
+    setVolume(clampedVolume);
+    setIsMuted(clampedVolume === 0);
+  };
+
+  const toggleMute = () => {
+    const nextMuted = !isMuted;
+    if (audioRef.current) {
+      audioRef.current.muted = nextMuted;
+    }
+    setIsMuted(nextMuted);
+  };
+
+  return (
+    <div
+      className={`image-canvas-editor__audio-card ${previewClassName} ${
+        isHovered ? 'image-canvas-editor__audio-card--controls-visible' : ''
+      }`}
+    >
+      <button
+        type="button"
+        className="image-canvas-editor__audio-card-playback"
+        aria-label={isPlaying ? `暂停${layer.title}` : `播放${layer.title}`}
+        onClick={(event) => {
+          event.stopPropagation();
+          void togglePlayback();
+        }}
+        onPointerDown={(event) => selectMediaLayerWithoutDrag(event, onSelectLayer)}
+      >
+        {showPlaybackButton ? (
+          isPlaying ? (
+            <Pause className="h-8 w-8" aria-hidden="true" />
+          ) : (
+            <Play className="h-8 w-8" aria-hidden="true" />
+          )
+        ) : (
+          getAudioLayerIcon(layer)
+        )}
+      </button>
+      {prompt ? (
+        <span className="image-canvas-editor__audio-card-title">{prompt}</span>
+      ) : null}
+      <div
+        className="image-canvas-editor__audio-card-controls image-canvas-editor__audio-card-controls--integrated"
+        onClick={stopMediaEventPropagation}
+        onKeyDown={stopMediaControlKeyPropagation}
+        onPointerDown={(event) => selectMediaLayerWithoutDrag(event, onSelectLayer)}
+      >
+        <audio
+          ref={audioRef}
+          className="image-canvas-editor__audio-card-native-control"
+          src={resolvedUrl || undefined}
+          preload="metadata"
+          aria-label={`画布音频：${layer.title}`}
+          onClick={stopMediaEventPropagation}
+          onPointerDown={(event) => selectMediaLayerWithoutDrag(event, onSelectLayer)}
+          onLoadedMetadata={(event) => {
+            const nextDuration = event.currentTarget.duration;
+            setDuration(
+              Number.isFinite(nextDuration) && nextDuration > 0
+                ? nextDuration
+                : fallbackDuration,
+            );
+          }}
+          onTimeUpdate={(event) => setCurrentTime(event.currentTarget.currentTime)}
+          onVolumeChange={(event) => {
+            setVolume(event.currentTarget.volume);
+            setIsMuted(event.currentTarget.muted);
+          }}
+          onPlay={() => setIsPlaying(true)}
+          onPause={() => setIsPlaying(false)}
+          onEnded={() => setIsPlaying(false)}
+        />
+        <span className="image-canvas-editor__audio-card-time">
+          {formatAudioControlTime(safeCurrentTime)}
+        </span>
+        <input
+          type="range"
+          className="image-canvas-editor__audio-card-progress"
+          min="0"
+          max={controlDuration || 0}
+          step="0.1"
+          value={safeCurrentTime}
+          disabled={!controlDuration}
+          aria-label={`调整${layer.title}播放进度`}
+          onChange={(event) => handleSeekChange(event.currentTarget.value)}
+        />
+        <span className="image-canvas-editor__audio-card-time">
+          {formatAudioControlTime(controlDuration)}
+        </span>
+        <button
+          type="button"
+          className="image-canvas-editor__audio-card-volume-toggle"
+          aria-label={isMuted ? `恢复${layer.title}音量` : `静音${layer.title}`}
+          onClick={(event) => {
+            event.stopPropagation();
+            toggleMute();
+          }}
+          onPointerDown={(event) => selectMediaLayerWithoutDrag(event, onSelectLayer)}
+        >
+          {isMuted ? (
+            <VolumeX className="h-3.5 w-3.5" aria-hidden="true" />
+          ) : (
+            <Volume2 className="h-3.5 w-3.5" aria-hidden="true" />
+          )}
+        </button>
+        <input
+          type="range"
+          className="image-canvas-editor__audio-card-volume"
+          min="0"
+          max="1"
+          step="0.01"
+          value={isMuted ? 0 : volume}
+          aria-label={`调整${layer.title}音量`}
+          onChange={(event) => handleVolumeChange(event.currentTarget.value)}
+        />
+      </div>
+    </div>
+  );
+}
+
+function ImageCanvasVideoLayer({
+  layer,
+  mediaTransform,
+}: {
+  layer: CanvasLayer;
+  mediaTransform?: string;
+}) {
+  const { resolvedUrl } = useResolvedAssetReadUrl(layer.src, {
+    objectKey: layer.objectKey,
+    refreshKey: layer.taskId ?? layer.resourceId,
+  });
+  const [showGeneratedPreview, setShowGeneratedPreview] = useState(
+    !layer.thumbnailSrc,
+  );
+  const previewClassName = getCanvasMediaPreviewClassName(
+    getCanvasMediaPreviewMarker(layer),
+  );
+
+  useEffect(() => {
+    setShowGeneratedPreview(!layer.thumbnailSrc);
+  }, [layer.src, layer.thumbnailSrc]);
+
+  return (
+    <>
+      <video
+        className="image-canvas-editor__layer-video"
+        src={resolvedUrl || undefined}
+        poster={layer.thumbnailSrc ?? undefined}
+        controls
+        playsInline
+        preload="metadata"
+        aria-label={`画布视频：${layer.title}`}
+        style={{ transform: mediaTransform }}
+        onLoadedData={() => setShowGeneratedPreview(false)}
+        onPlay={() => setShowGeneratedPreview(false)}
+        onClick={(event) => event.stopPropagation()}
+        onPointerDown={(event) => {
+          if (event.target !== event.currentTarget) {
+            event.stopPropagation();
+          }
+        }}
+      />
+      <span
+        className={`image-canvas-editor__layer-video-preview ${previewClassName} ${
+          showGeneratedPreview
+            ? 'image-canvas-editor__layer-video-preview--visible'
+            : ''
+        }`}
+        aria-hidden="true"
+      />
+    </>
+  );
+}
+
+function ImageCanvasImageLayer({
+  layer,
+  mediaTransform,
+}: {
+  layer: CanvasLayer;
+  mediaTransform?: string;
+}) {
+  const { resolvedUrl } = useResolvedAssetReadUrl(layer.src, {
+    objectKey: layer.objectKey,
+    refreshKey: layer.taskId ?? layer.resourceId,
+  });
+
+  return (
+    <img
+      src={resolvedUrl || undefined}
+      alt={`画布图片：${layer.title}`}
+      style={{ transform: mediaTransform }}
+    />
+  );
+}
+
+export function ImageCanvasWorldView({
+  viewport,
+  snapGuide,
+  layers,
+  selectedLayerIds,
+  hoveredLayerId,
+  canvasMarquee,
+  canvasGenerationDialogs,
+  generateDialog,
+  cropExpandPanel,
+  cropExpandSourceLayer,
+  generationComposerStyle,
+  onLayerPointerDown,
+  onLayerClick,
+  onSelectLayer,
+  onLayerContextMenu,
+  onLayerMouseEnter,
+  onLayerMouseLeave,
+  onOpenLayerMetadata,
+  onUpdateLayerAssetKind,
+  onGenerationFramePointerDown,
+  onActivateGenerationDialog,
+  onCropExpandHandlePointerDown,
+}: ImageCanvasWorldViewProps) {
+  const inverseScale = getInverseViewportScale(viewport);
+  const inverseScaleStyle = buildInverseScaleStyle(inverseScale);
+  const [openLayerKindMenuId, setOpenLayerKindMenuId] = useState<string | null>(
+    null,
+  );
+  const openLayerKindTriggerRef = useRef<HTMLSpanElement | null>(null);
+  const openLayerKindMenuRef = useRef<HTMLDivElement | null>(null);
+  const visibleLayers = useMemo(
+    () =>
+      layers
+        .filter((layer) => !layer.hidden)
+        .slice()
+        .sort((left, right) => left.zIndex - right.zIndex),
+    [layers],
+  );
+
+  useEffect(() => {
+    if (!openLayerKindMenuId) {
+      return undefined;
+    }
+
+    const closeKindMenuWhenClickingOutside = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+      if (
+        openLayerKindMenuRef.current?.contains(target) ||
+        openLayerKindTriggerRef.current?.contains(target)
+      ) {
+        return;
+      }
+      setOpenLayerKindMenuId(null);
+    };
+
+    document.addEventListener('pointerdown', closeKindMenuWhenClickingOutside);
+    return () => {
+      document.removeEventListener(
+        'pointerdown',
+        closeKindMenuWhenClickingOutside,
+      );
+    };
+  }, [openLayerKindMenuId]);
+
+  return (
+    <div
+      className="image-canvas-editor__world"
+      style={{
+        width: CANVAS_WORLD_SIZE,
+        height: CANVAS_WORLD_SIZE,
+        transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.scale})`,
+      }}
+    >
+      {snapGuide?.vertical !== undefined ? (
+        <div
+          className="image-canvas-editor__snap-guide image-canvas-editor__snap-guide--vertical"
+          data-testid="image-canvas-editor-snap-guide-vertical"
+          style={{ left: snapGuide.vertical }}
+        />
+      ) : null}
+      {snapGuide?.horizontal !== undefined ? (
+        <div
+          className="image-canvas-editor__snap-guide image-canvas-editor__snap-guide--horizontal"
+          data-testid="image-canvas-editor-snap-guide-horizontal"
+          style={{ top: snapGuide.horizontal }}
+        />
+      ) : null}
+
+      {visibleLayers.map((layer) => {
+          const isSelected = selectedLayerIds.includes(layer.id);
+          const isHovered = hoveredLayerId === layer.id;
+          const kindTagMeta = getLayerKindTagMeta(layer);
+          const kindLabel = kindTagMeta.label;
+          const mediaTransform =
+            layer.flipX || layer.flipY
+              ? `scale(${layer.flipX ? -1 : 1}, ${layer.flipY ? -1 : 1})`
+              : undefined;
+          const layerGeneratingLabel =
+            generateDialog?.mode === 'edit' &&
+            generateDialog.status === 'generating' &&
+            generateDialog.sourceLayerId === layer.id
+              ? '修改中'
+              : null;
+          const LayerElement =
+            layer.mediaType === 'audio' || layer.mediaType === 'video'
+              ? 'div'
+              : 'button';
+          return (
+            <div key={layer.id}>
+              <LayerElement
+                {...(layer.mediaType === 'audio' || layer.mediaType === 'video'
+                  ? { role: 'button', tabIndex: 0 }
+                  : { type: 'button' })}
+                className={`image-canvas-editor__layer ${isSelected ? 'image-canvas-editor__layer--selected' : ''} ${isHovered ? 'image-canvas-editor__layer--hovered' : ''} ${layerGeneratingLabel ? 'image-canvas-editor__layer--generating' : ''} ${layer.locked ? 'image-canvas-editor__layer--locked' : ''}`}
+                style={{
+                  left: layer.x,
+                  top: layer.y,
+                  width: layer.width,
+                  height: layer.height,
+                  zIndex: layer.zIndex,
+                  display: layer.hidden ? 'none' : undefined,
+                }}
+                onPointerDown={(event) => onLayerPointerDown(event, layer)}
+                onClick={(event) => {
+                  setOpenLayerKindMenuId(null);
+                  onLayerClick(event, layer);
+                }}
+                onContextMenu={(event) => {
+                  setOpenLayerKindMenuId(null);
+                  onLayerContextMenu(event, layer);
+                }}
+                onKeyDown={
+                  layer.mediaType === 'audio' || layer.mediaType === 'video'
+                    ? handleLayerKeyboardActivation
+                    : undefined
+                }
+                onMouseEnter={() => onLayerMouseEnter(layer.id)}
+                onMouseLeave={() => onLayerMouseLeave(layer.id)}
+                aria-label={`选择${layer.title}`}
+              >
+                {layer.mediaType === 'audio' ? (
+                  <ImageCanvasAudioLayerCard
+                    layer={layer}
+                    isHovered={isHovered}
+                    onSelectLayer={() => onSelectLayer(layer.id)}
+                  />
+                ) : layer.mediaType === 'video' ? (
+                  <ImageCanvasVideoLayer
+                    layer={layer}
+                    mediaTransform={mediaTransform}
+                  />
+                ) : (
+                  <ImageCanvasImageLayer
+                    layer={layer}
+                    mediaTransform={mediaTransform}
+                  />
+                )}
+                {kindLabel ? (
+                  <span
+                    ref={
+                      openLayerKindMenuId === layer.id
+                        ? openLayerKindTriggerRef
+                        : undefined
+                    }
+                    role="button"
+                    tabIndex={0}
+                    aria-label={`素材标签：${kindLabel}`}
+                    className={`image-canvas-editor__kind-badge image-canvas-editor__kind-badge--${kindTagMeta.className} image-canvas-editor__kind-badge--beside-info image-canvas-editor__kind-badge--editable`}
+                    style={inverseScaleStyle}
+                    onPointerDown={(event) => event.stopPropagation()}
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      setOpenLayerKindMenuId((currentId) =>
+                        currentId === layer.id ? null : layer.id,
+                      );
+                    }}
+                    onKeyDown={handleLayerTagKeyboardActivation}
+                  >
+                    {kindLabel}
+                  </span>
+                ) : null}
+                <PlatformIconButton
+                  asChild="spanButton"
+                  variant="darkMini"
+                  className="image-canvas-editor__metadata-corner"
+                  label={`查看${layer.title}${
+                    layer.mediaType === 'audio'
+                      ? '音频'
+                      : layer.mediaType === 'video'
+                        ? '视频'
+                        : '图片'
+                  }信息`}
+                  icon={<Info className="h-3 w-3" />}
+                  style={inverseScaleStyle}
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    onOpenLayerMetadata(layer);
+                  }}
+                  onPointerDown={(event) => event.stopPropagation()}
+                />
+                {isHovered && layer.mediaType !== 'audio' ? (
+                  <PlatformPillBadge
+                    tone="lightOverlay"
+                    size="xs"
+                    className="image-canvas-editor__size-badge"
+                    style={inverseScaleStyle}
+                  >
+                    {getLayerMetricLabel(layer)}
+                  </PlatformPillBadge>
+                ) : null}
+                {layerGeneratingLabel ? (
+                  <span
+                    className="image-canvas-editor__generation-frame-progress image-canvas-editor__layer-generating-progress"
+                    role="status"
+                  >
+                    {layerGeneratingLabel}
+                  </span>
+                ) : null}
+              </LayerElement>
+              {openLayerKindMenuId === layer.id ? (
+                <div
+                  ref={openLayerKindMenuRef}
+                  className="image-canvas-editor__kind-menu-anchor"
+                  style={{
+                    left: layer.x + layer.width,
+                    top: layer.y,
+                    zIndex: layer.zIndex + 30,
+                    ...inverseScaleStyle,
+                  }}
+                >
+                  <PlatformFloatingMenu
+                    label="选择素材标签"
+                    placement="bottom-end"
+                    className="image-canvas-editor__kind-menu"
+                    onWheelCapture={(event) => event.stopPropagation()}
+                    onWheel={(event) => event.stopPropagation()}
+                  >
+                    {CANVAS_ASSET_KIND_TAG_OPTIONS.map((option) => (
+                      <PlatformFloatingMenuItem
+                        key={option.value ?? 'unknown'}
+                        className={
+                          option.value === (layer.assetKind ?? null)
+                            ? 'image-canvas-editor__kind-menu-item--active'
+                            : undefined
+                        }
+                        onClick={(event) => {
+                          event.stopPropagation();
+                          onUpdateLayerAssetKind(layer.id, option.value);
+                          setOpenLayerKindMenuId(null);
+                        }}
+                      >
+                        {option.label}
+                      </PlatformFloatingMenuItem>
+                    ))}
+                  </PlatformFloatingMenu>
+                </div>
+              ) : null}
+            </div>
+          );
+        })}
+      {canvasMarquee ? (
+        <div
+          className="image-canvas-editor__canvas-marquee"
+          aria-hidden="true"
+          style={{
+            left:
+              (Math.min(canvasMarquee.startX, canvasMarquee.currentX) -
+                viewport.x) /
+              viewport.scale,
+            top:
+              (Math.min(canvasMarquee.startY, canvasMarquee.currentY) -
+                viewport.y) /
+              viewport.scale,
+            width:
+              Math.abs(canvasMarquee.currentX - canvasMarquee.startX) /
+              viewport.scale,
+            height:
+              Math.abs(canvasMarquee.currentY - canvasMarquee.startY) /
+              viewport.scale,
+          }}
+        />
+      ) : null}
+      {cropExpandPanel && cropExpandSourceLayer ? (
+        <div
+          className="image-canvas-editor__crop-expand-frame"
+          style={{
+            left: cropExpandPanel.frame.x,
+            top: cropExpandPanel.frame.y,
+            width: cropExpandPanel.frame.width,
+            height: cropExpandPanel.frame.height,
+          }}
+          aria-label="裁扩边界"
+          role="group"
+        >
+          <div
+            className="image-canvas-editor__crop-expand-source-mask"
+            aria-hidden="true"
+            style={{
+              left: cropExpandSourceLayer.x - cropExpandPanel.frame.x,
+              top: cropExpandSourceLayer.y - cropExpandPanel.frame.y,
+              width: cropExpandSourceLayer.width,
+              height: cropExpandSourceLayer.height,
+            }}
+          />
+          {CROP_EXPAND_HANDLES.map((handle) => (
+            <button
+              key={handle.value}
+              type="button"
+              className={`image-canvas-editor__crop-expand-handle image-canvas-editor__crop-expand-handle--${handle.value}`}
+              aria-label={`拖拽裁扩${handle.label}`}
+              onPointerDown={(event) =>
+                onCropExpandHandlePointerDown(event, handle.value)
+              }
+            />
+          ))}
+        </div>
+      ) : null}
+      {canvasGenerationDialogs.map((dialog) => {
+        const hasGeneratedLayer = Boolean(
+          dialog.generatedLayerId &&
+            layers.some((layer) => layer.id === dialog.generatedLayerId),
+        );
+        return dialog.placeholder && !hasGeneratedLayer
+          ? (() => {
+              const isFocused = generateDialog?.id === dialog.id;
+              const isSelected = selectedLayerIds.includes(
+                getCanvasGenerationSelectionId(dialog.id),
+              );
+              const showFocusedChrome =
+                isFocused || isSelected || dialog.status === 'generating';
+              const placeholderMeta = getGenerationPlaceholderMeta(dialog);
+
+              return (
+                <div
+                  key={dialog.id}
+                  className={`image-canvas-editor__generation-frame ${
+                    placeholderMeta.frameClassName
+                  } ${
+                    dialog.status === 'generating'
+                      ? 'image-canvas-editor__generation-frame--generating'
+                      : ''
+                  } ${
+                    isFocused || isSelected
+                      ? 'image-canvas-editor__generation-frame--focused'
+                      : ''
+                  }`}
+                  role="button"
+                  tabIndex={0}
+                  style={{
+                    left: dialog.placeholder.x,
+                    top: dialog.placeholder.y,
+                    width: dialog.placeholder.width,
+                    height: dialog.placeholder.height,
+                  }}
+                  aria-label={getGenerationFrameAriaLabel(dialog)}
+                  onPointerDown={(event) =>
+                    onGenerationFramePointerDown(event, dialog)
+                  }
+                  onDoubleClick={() => onActivateGenerationDialog(dialog)}
+                >
+                  {showFocusedChrome ? (
+                    <span
+                      className="image-canvas-editor__generation-frame-label"
+                      style={inverseScaleStyle}
+                    >
+                      {placeholderMeta.labelIcon}
+                      {getGenerationFrameLabel(dialog)}
+                    </span>
+                  ) : null}
+                  {placeholderMeta.badgeLabel ? (
+                    <span
+                      className={`image-canvas-editor__kind-badge image-canvas-editor__kind-badge--${placeholderMeta.badgeClassName}`}
+                      style={inverseScaleStyle}
+                    >
+                      {placeholderMeta.badgeLabel}
+                    </span>
+                  ) : null}
+                  {showFocusedChrome &&
+                  dialog.mode !== 'audio-sound-effect' &&
+                  dialog.mode !== 'audio-background-music' ? (
+                    <span
+                      className="image-canvas-editor__generation-frame-size"
+                      style={inverseScaleStyle}
+                    >
+                      {`${dialog.placeholder.originalWidth} x ${dialog.placeholder.originalHeight}`}
+                    </span>
+                  ) : null}
+                  <span
+                    className="image-canvas-editor__generation-frame-icon"
+                    style={inverseScaleStyle}
+                  >
+                    {placeholderMeta.icon}
+                  </span>
+                  {dialog.status === 'generating' ? (
+                    <span
+                      className="image-canvas-editor__generation-frame-progress"
+                      role="status"
+                    >
+                      生成中
+                    </span>
+                  ) : null}
+                </div>
+              );
+            })()
+          : null;
+      })}
+      {(generateDialog?.mode === 'generate' ||
+        generateDialog?.mode === 'spec' ||
+        generateDialog?.mode === 'character' ||
+        generateDialog?.mode === 'icon' ||
+        generateDialog?.mode === 'ui-design' ||
+        generateDialog?.mode === 'quick-edit' ||
+        generateDialog?.mode === 'publication' ||
+        generateDialog?.mode === 'character-animation' ||
+        generateDialog?.mode === 'video' ||
+        generateDialog?.mode === 'audio-sound-effect' ||
+        generateDialog?.mode === 'audio-background-music') &&
+      generateDialog.status === 'generating' &&
+      generationComposerStyle ? (
+        <PlatformStatusMessage
+          tone="info"
+          surface="platform"
+          size="xs"
+          className="image-canvas-editor__generate-status image-canvas-editor__generate-status--floating"
+          role="status"
+          style={generationComposerStyle}
+        >
+          生成中
+        </PlatformStatusMessage>
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.test.tsx b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
new file mode 100644
index 000000000..b933c82cc
--- /dev/null
+++ b/src/components/image-editor/useCanvasGenerationDialogs.test.tsx
@@ -0,0 +1,260 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasGenerationDialogState } from './ImageCanvasEditorTypes';
+import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
+
+function createDialog(
+  mode: CanvasGenerationDialogState['mode'],
+  prompt: string,
+): Omit<CanvasGenerationDialogState, 'id'> {
+  return {
+    mode,
+    prompt,
+    status: 'idle',
+    composerOpen: true,
+    placeholder: {
+      x: mode === 'character' ? 30 : 10,
+      y: mode === 'character' ? 40 : 20,
+      width: 320,
+      height: 240,
+      originalWidth: 320,
+      originalHeight: 240,
+    },
+  };
+}
+
+function GenerationDialogsHarness({ onActivate }: { onActivate: () => void }) {
+  const dialogs = useCanvasGenerationDialogs({ onActivate });
+  const activeId = dialogs.activeCanvasGenerationDialog?.id ?? '-';
+  const activePrompt = dialogs.activeCanvasGenerationDialog?.prompt ?? '-';
+  const inactiveIds = dialogs.inactiveGenerateDialogs
+    .map((dialog) => `${dialog.id}:${dialog.prompt}:${dialog.composerOpen}`)
+    .join('|');
+  const allPrompts = dialogs.canvasGenerationDialogs
+    .map((dialog) => dialog.prompt)
+    .join(',');
+
+  return (
+    <div>
+      <span data-testid="active-id">{activeId}</span>
+      <span data-testid="active-prompt">{activePrompt}</span>
+      <span data-testid="inactive">{inactiveIds}</span>
+      <span data-testid="all-prompts">{allPrompts}</span>
+      <span data-testid="placeholder-x">
+        {String(
+          dialogs.getGeneratingDialogPlaceholder(
+            dialogs.activeCanvasGenerationDialog ?? {
+              mode: 'generate',
+              prompt: 'fallback',
+              status: 'idle',
+            },
+          )?.x ?? '-',
+        )}
+      </span>
+      <button
+        type="button"
+        onClick={() => dialogs.openCanvasGenerationDialog(createDialog('generate', 'first'))}
+      >
+        open first
+      </button>
+      <button
+        type="button"
+        onClick={() => dialogs.openCanvasGenerationDialog(createDialog('character', 'second'))}
+      >
+        open second
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const target = dialogs.inactiveGenerateDialogs[0];
+          if (target) {
+            dialogs.activateCanvasGenerationDialog(target);
+          }
+        }}
+      >
+        activate inactive
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const target = dialogs.activeCanvasGenerationDialog;
+          if (target) {
+            dialogs.updateCanvasGenerationDialogById(target.id, (dialog) => ({
+              ...dialog,
+              status: 'generating',
+              placeholder: dialog.placeholder
+                ? {
+                    ...dialog.placeholder,
+                    x: 99,
+                  }
+                : dialog.placeholder,
+            }));
+          }
+        }}
+      >
+        update active
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const target = dialogs.activeCanvasGenerationDialog;
+          if (target) {
+            dialogs.removeCanvasGenerationDialogById(target.id);
+          }
+        }}
+      >
+        remove active
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const target = dialogs.activeCanvasGenerationDialog;
+          if (target) {
+            dialogs.updateCanvasGenerationDialogById(target.id, (dialog) => ({
+              ...dialog,
+              sourceLayerId: 'layer-a',
+            }));
+          }
+        }}
+      >
+        bind layer
+      </button>
+      <button
+        type="button"
+        onClick={() => dialogs.removeCanvasGenerationDialogsByLayerId('layer-a')}
+      >
+        remove layer dialogs
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.restoreCanvasGenerationDialogs([
+            {
+              id: 'generation-dialog-12',
+              mode: 'generate',
+              prompt: 'restored',
+              status: 'idle',
+              composerOpen: true,
+              placeholder: {
+                x: 12,
+                y: 24,
+                width: 320,
+                height: 240,
+                originalWidth: 320,
+                originalHeight: 240,
+              },
+            },
+          ])
+        }
+      >
+        restore saved
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.restoreCanvasGenerationDialogs([
+            {
+              id: 'generation-dialog-2',
+              mode: 'generate',
+              prompt: 'inactive saved',
+              status: 'idle',
+              composerOpen: false,
+            },
+            {
+              id: 'generation-dialog-3',
+              mode: 'character',
+              prompt: 'active saved',
+              status: 'idle',
+              composerOpen: true,
+            },
+          ])
+        }
+      >
+        restore active
+      </button>
+    </div>
+  );
+}
+
+describe('useCanvasGenerationDialogs', () => {
+  it('archives, activates, updates, and removes canvas generation dialogs', () => {
+    const onActivate = vi.fn();
+    render(<GenerationDialogsHarness onActivate={onActivate} />);
+
+    act(() => screen.getByRole('button', { name: 'open first' }).click());
+    expect(screen.getByTestId('active-prompt').textContent).toBe('first');
+    expect(screen.getByTestId('all-prompts').textContent).toBe('first');
+
+    act(() => screen.getByRole('button', { name: 'open second' }).click());
+    expect(screen.getByTestId('active-prompt').textContent).toBe('second');
+    expect(screen.getByTestId('inactive').textContent).toContain(
+      'generation-dialog-1:first:false',
+    );
+    expect(screen.getByTestId('all-prompts').textContent).toBe(
+      'first,second',
+    );
+
+    act(() =>
+      screen.getByRole('button', { name: 'activate inactive' }).click(),
+    );
+    expect(onActivate).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId('active-prompt').textContent).toBe('first');
+    expect(screen.getByTestId('inactive').textContent).toContain(
+      'generation-dialog-2:second:false',
+    );
+
+    act(() => screen.getByRole('button', { name: 'update active' }).click());
+    expect(screen.getByTestId('placeholder-x').textContent).toBe('99');
+
+    act(() => screen.getByRole('button', { name: 'bind layer' }).click());
+    act(() =>
+      screen.getByRole('button', { name: 'remove layer dialogs' }).click(),
+    );
+    expect(screen.getByTestId('active-prompt').textContent).toBe('-');
+    expect(screen.getByTestId('inactive').textContent).toContain('second');
+
+    act(() => screen.getByRole('button', { name: 'activate inactive' }).click());
+    act(() => screen.getByRole('button', { name: 'remove active' }).click());
+    expect(screen.getByTestId('active-prompt').textContent).toBe('-');
+    expect(screen.getByTestId('inactive').textContent).toBe('');
+  });
+
+  it('restores saved dialogs and continues ids after the saved maximum', () => {
+    const onActivate = vi.fn();
+    render(<GenerationDialogsHarness onActivate={onActivate} />);
+
+    act(() => screen.getByRole('button', { name: 'restore saved' }).click());
+    expect(screen.getByTestId('active-id').textContent).toBe(
+      'generation-dialog-12',
+    );
+    expect(screen.getByTestId('active-prompt').textContent).toBe('restored');
+
+    act(() => screen.getByRole('button', { name: 'open second' }).click());
+    expect(screen.getByTestId('active-id').textContent).toBe(
+      'generation-dialog-13',
+    );
+    expect(screen.getByTestId('inactive').textContent).toContain(
+      'generation-dialog-12:restored:false',
+    );
+  });
+
+  it('keeps the saved open dialog active when restoring multiple dialogs', () => {
+    const onActivate = vi.fn();
+    render(<GenerationDialogsHarness onActivate={onActivate} />);
+
+    act(() => screen.getByRole('button', { name: 'restore active' }).click());
+
+    expect(screen.getByTestId('active-id').textContent).toBe(
+      'generation-dialog-3',
+    );
+    expect(screen.getByTestId('active-prompt').textContent).toBe(
+      'active saved',
+    );
+    expect(screen.getByTestId('inactive').textContent).toContain(
+      'generation-dialog-2:inactive saved:false',
+    );
+  });
+});
diff --git a/src/components/image-editor/useCanvasGenerationDialogs.ts b/src/components/image-editor/useCanvasGenerationDialogs.ts
new file mode 100644
index 000000000..7f8ce3889
--- /dev/null
+++ b/src/components/image-editor/useCanvasGenerationDialogs.ts
@@ -0,0 +1,267 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import { isCanvasGenerationDialog } from './ImageCanvasGenerationModel';
+import type {
+  CanvasGenerationDialogState,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+
+type CanvasGenerationDialogUpdater = (
+  dialog: CanvasGenerationDialogState,
+) => CanvasGenerationDialogState | null;
+
+export function useCanvasGenerationDialogs({
+  onActivate,
+}: {
+  onActivate?: () => void;
+} = {}) {
+  const generationDialogCounterRef = useRef(0);
+  const generateDialogRef = useRef<GenerateDialogState | null>(null);
+  const inactiveGenerateDialogsRef = useRef<CanvasGenerationDialogState[]>([]);
+  const [generateDialog, setGenerateDialog] =
+    useState<GenerateDialogState | null>(null);
+  const [inactiveGenerateDialogs, setInactiveGenerateDialogs] = useState<
+    CanvasGenerationDialogState[]
+  >([]);
+
+  generateDialogRef.current = generateDialog;
+  inactiveGenerateDialogsRef.current = inactiveGenerateDialogs;
+
+  const activeCanvasGenerationDialog = isCanvasGenerationDialog(generateDialog)
+    ? generateDialog
+    : null;
+  const canvasGenerationDialogs = useMemo(
+    () =>
+      activeCanvasGenerationDialog
+        ? [...inactiveGenerateDialogs, activeCanvasGenerationDialog]
+        : inactiveGenerateDialogs,
+    [activeCanvasGenerationDialog, inactiveGenerateDialogs],
+  );
+
+  const createGenerationDialogId = useCallback(() => {
+    generationDialogCounterRef.current += 1;
+    return `generation-dialog-${generationDialogCounterRef.current}`;
+  }, []);
+
+  const archiveActiveCanvasGenerationDialog = useCallback(() => {
+    const currentDialog = generateDialogRef.current;
+    if (!isCanvasGenerationDialog(currentDialog)) {
+      return;
+    }
+    setInactiveGenerateDialogs((currentDialogs) =>
+      currentDialogs.some((dialog) => dialog.id === currentDialog.id)
+        ? currentDialogs
+        : [
+            ...currentDialogs,
+            {
+              ...currentDialog,
+              composerOpen: false,
+            },
+          ],
+    );
+  }, []);
+
+  const openCanvasGenerationDialog = useCallback(
+    (dialog: Omit<CanvasGenerationDialogState, 'id'>) => {
+      const currentDialog = generateDialogRef.current;
+      if (isCanvasGenerationDialog(currentDialog)) {
+        inactiveGenerateDialogsRef.current =
+          inactiveGenerateDialogsRef.current.some(
+            (existingDialog) => existingDialog.id === currentDialog.id,
+          )
+            ? inactiveGenerateDialogsRef.current
+            : [
+                ...inactiveGenerateDialogsRef.current,
+                {
+                  ...currentDialog,
+                  composerOpen: false,
+                },
+              ];
+      }
+      archiveActiveCanvasGenerationDialog();
+      const id = createGenerationDialogId();
+      const nextDialog = {
+        ...dialog,
+        id,
+      };
+      generateDialogRef.current = nextDialog;
+      setGenerateDialog(nextDialog);
+      return id;
+    },
+    [archiveActiveCanvasGenerationDialog, createGenerationDialogId],
+  );
+
+  const updateCanvasGenerationDialogById = useCallback(
+    (dialogId: string, updater: CanvasGenerationDialogUpdater) => {
+      const currentDialogRef = generateDialogRef.current;
+      if (
+        isCanvasGenerationDialog(currentDialogRef) &&
+        currentDialogRef.id === dialogId
+      ) {
+        generateDialogRef.current = updater(currentDialogRef);
+      }
+      inactiveGenerateDialogsRef.current =
+        inactiveGenerateDialogsRef.current.flatMap((dialog) => {
+          if (dialog.id !== dialogId) {
+            return [dialog];
+          }
+          const nextDialog = updater(dialog);
+          return nextDialog ? [nextDialog] : [];
+        });
+      setGenerateDialog((currentDialog) =>
+        isCanvasGenerationDialog(currentDialog) &&
+        currentDialog.id === dialogId
+          ? updater(currentDialog)
+          : currentDialog,
+      );
+      setInactiveGenerateDialogs((currentDialogs) =>
+        currentDialogs.flatMap((dialog) => {
+          if (dialog.id !== dialogId) {
+            return [dialog];
+          }
+          const nextDialog = updater(dialog);
+          return nextDialog ? [nextDialog] : [];
+        }),
+      );
+    },
+    [],
+  );
+
+  const removeCanvasGenerationDialogById = useCallback(
+    (dialogId: string) => {
+      updateCanvasGenerationDialogById(dialogId, () => null);
+    },
+    [updateCanvasGenerationDialogById],
+  );
+
+  const hasCanvasGenerationDialogById = useCallback((dialogId: string) => {
+    const currentDialog = generateDialogRef.current;
+    return [
+      ...(isCanvasGenerationDialog(currentDialog) ? [currentDialog] : []),
+      ...inactiveGenerateDialogsRef.current,
+    ].some((dialog) => dialog.id === dialogId);
+  }, []);
+
+  const activateCanvasGenerationDialog = useCallback(
+    (targetDialog: CanvasGenerationDialogState) => {
+      setInactiveGenerateDialogs((currentDialogs) => {
+        const nextDialogs = currentDialogs.filter(
+          (dialog) => dialog.id !== targetDialog.id,
+        );
+        const currentDialog = generateDialogRef.current;
+        if (
+          isCanvasGenerationDialog(currentDialog) &&
+          currentDialog.id !== targetDialog.id
+        ) {
+          nextDialogs.push({
+            ...currentDialog,
+            composerOpen: false,
+          });
+        }
+        return nextDialogs;
+      });
+      setGenerateDialog({
+        ...targetDialog,
+        composerOpen: true,
+      });
+      onActivate?.();
+    },
+    [onActivate],
+  );
+
+  const restoreCanvasGenerationDialogs = useCallback(
+    (dialogs: CanvasGenerationDialogState[]) => {
+      const nextCounter = dialogs.reduce((maxCounter, dialog) => {
+        const match = /^generation-dialog-(\d+)$/u.exec(dialog.id);
+        const numericId = match ? Number.parseInt(match[1] ?? '0', 10) : 0;
+        return Math.max(maxCounter, Number.isFinite(numericId) ? numericId : 0);
+      }, 0);
+      generationDialogCounterRef.current = Math.max(
+        generationDialogCounterRef.current,
+        nextCounter,
+      );
+      const activeDialog =
+        [...dialogs].reverse().find((dialog) => dialog.composerOpen !== false) ??
+        dialogs[dialogs.length - 1] ??
+        null;
+      setGenerateDialog(
+        activeDialog
+          ? {
+              ...activeDialog,
+              composerOpen: activeDialog.composerOpen !== false,
+            }
+          : null,
+      );
+      setInactiveGenerateDialogs(
+        dialogs
+          .filter((dialog) => dialog.id !== activeDialog?.id)
+          .map((dialog) => ({
+            ...dialog,
+            composerOpen: false,
+          })),
+      );
+    },
+    [],
+  );
+
+  const removeCanvasGenerationDialogsByLayerId = useCallback(
+    (targetLayerId: string) => {
+      const keepDialog = (dialog: CanvasGenerationDialogState) =>
+        dialog.sourceLayerId !== targetLayerId &&
+        dialog.generatedLayerId !== targetLayerId;
+      setGenerateDialog((currentDialog) =>
+        isCanvasGenerationDialog(currentDialog) && !keepDialog(currentDialog)
+          ? null
+          : currentDialog,
+      );
+      setInactiveGenerateDialogs((currentDialogs) =>
+        currentDialogs.filter(keepDialog),
+      );
+    },
+    [],
+  );
+
+  const getGeneratingDialogPlaceholder = useCallback(
+    (dialog: GenerateDialogState) => {
+      const currentDialog = generateDialogRef.current;
+      if (dialog.id) {
+        const latestDialog = [
+          ...(isCanvasGenerationDialog(currentDialog) ? [currentDialog] : []),
+          ...inactiveGenerateDialogsRef.current,
+        ].find((candidateDialog) => candidateDialog.id === dialog.id);
+        if (latestDialog?.status === 'generating') {
+          return latestDialog.placeholder ?? dialog.placeholder;
+        }
+      }
+      if (
+        currentDialog?.mode === dialog.mode &&
+        (!dialog.id || currentDialog.id === dialog.id) &&
+        currentDialog.status === 'generating'
+      ) {
+        return currentDialog.placeholder ?? dialog.placeholder;
+      }
+      return dialog.placeholder;
+    },
+    [],
+  );
+
+  return {
+    generateDialog,
+    setGenerateDialog,
+    generateDialogRef,
+    inactiveGenerateDialogs,
+    setInactiveGenerateDialogs,
+    inactiveGenerateDialogsRef,
+    activeCanvasGenerationDialog,
+    canvasGenerationDialogs,
+    archiveActiveCanvasGenerationDialog,
+    openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    removeCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById,
+    activateCanvasGenerationDialog,
+    restoreCanvasGenerationDialogs,
+    removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder,
+  };
+}
diff --git a/src/components/image-editor/useCanvasHistory.test.tsx b/src/components/image-editor/useCanvasHistory.test.tsx
new file mode 100644
index 000000000..5e9c502b1
--- /dev/null
+++ b/src/components/image-editor/useCanvasHistory.test.tsx
@@ -0,0 +1,213 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import { useCanvasHistory } from './useCanvasHistory';
+
+function createLayer(id: string, x: number): CanvasLayer {
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x,
+    y: 20,
+    width: 100,
+    height: 80,
+    originalWidth: 100,
+    originalHeight: 80,
+    zIndex: 1,
+    sourceType: 'uploaded',
+  };
+}
+
+function HistoryHarness({ onClearDrag }: { onClearDrag: () => void }) {
+  const [layers, setLayers] = useState<CanvasLayer[]>([
+    createLayer('first', 10),
+  ]);
+  const [viewport, setViewport] = useState<CanvasViewport>({
+    x: 1,
+    y: 2,
+    scale: 1,
+  });
+  const [generateDialog, setGenerateDialog] =
+    useState<GenerateDialogState | null>({
+      id: 'dialog-active',
+      mode: 'generate',
+      prompt: 'active prompt',
+      status: 'idle',
+      placeholder: {
+        x: 10,
+        y: 20,
+        width: 320,
+        height: 240,
+        originalWidth: 320,
+        originalHeight: 240,
+      },
+    });
+  const [inactiveGenerateDialogs, setInactiveGenerateDialogs] = useState<
+    CanvasGenerationDialogState[]
+  >([
+    {
+      id: 'dialog-inactive',
+      mode: 'character',
+      prompt: 'archived prompt',
+      status: 'idle',
+      placeholder: {
+        x: 30,
+        y: 40,
+        width: 512,
+        height: 512,
+        originalWidth: 512,
+        originalHeight: 512,
+      },
+    },
+  ]);
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>('first');
+  const [selectedLayerIds, setSelectedLayerIds] = useState<string[]>(['first']);
+
+  const layersRef = useRef(layers);
+  const viewportRef = useRef(viewport);
+  const generateDialogRef = useRef(generateDialog);
+  const inactiveGenerateDialogsRef = useRef(inactiveGenerateDialogs);
+  const selectedLayerIdRef = useRef(selectedLayerId);
+  const selectedLayerIdsRef = useRef(selectedLayerIds);
+
+  layersRef.current = layers;
+  viewportRef.current = viewport;
+  generateDialogRef.current = generateDialog;
+  inactiveGenerateDialogsRef.current = inactiveGenerateDialogs;
+  selectedLayerIdRef.current = selectedLayerId;
+  selectedLayerIdsRef.current = selectedLayerIds;
+
+  const history = useCanvasHistory({
+    refs: {
+      layersRef,
+      viewportRef,
+      generateDialogRef,
+      inactiveGenerateDialogsRef,
+      selectedLayerIdRef,
+      selectedLayerIdsRef,
+    },
+    setters: {
+      setLayers,
+      setViewport,
+      setGenerateDialog,
+      setInactiveGenerateDialogs,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    },
+    resetters: {
+      setHoveredLayerId: () => {},
+      setMetadataLayer: () => {},
+      resetCanvasInteractionState: onClearDrag,
+    },
+  });
+
+  return (
+    <div>
+      <span data-testid="layers">
+        {layers.map((layer) => `${layer.id}:${layer.x}`).join(',')}
+      </span>
+      <span data-testid="viewport">
+        {viewport.x},{viewport.y},{viewport.scale}
+      </span>
+      <span data-testid="dialog">{generateDialog?.prompt ?? '-'}</span>
+      <span data-testid="inactive">
+        {inactiveGenerateDialogs.map((dialog) => dialog.prompt).join(',')}
+      </span>
+      <span data-testid="selection">{selectedLayerIds.join(',')}</span>
+      <span data-testid="can-undo">{String(history.canUndo)}</span>
+      <span data-testid="can-redo">{String(history.canRedo)}</span>
+      <button
+        type="button"
+        onClick={() => {
+          history.captureCanvasHistory();
+        }}
+      >
+        capture
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          setLayers([createLayer('second', 90)]);
+          setViewport({ x: 9, y: 8, scale: 2 });
+          setGenerateDialog({
+            id: 'dialog-next',
+            mode: 'spec',
+            prompt: 'next prompt',
+            status: 'idle',
+          });
+          setInactiveGenerateDialogs([]);
+          setSelectedLayerId('second');
+          setSelectedLayerIds(['second']);
+        }}
+      >
+        mutate
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          history.undoCanvasChange();
+        }}
+      >
+        undo
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          history.redoCanvasChange();
+        }}
+      >
+        redo
+      </button>
+    </div>
+  );
+}
+
+describe('useCanvasHistory', () => {
+  it('captures, restores, and replays canvas history snapshots', () => {
+    const clearDragState = vi.fn();
+    render(<HistoryHarness onClearDrag={clearDragState} />);
+
+    act(() => {
+      screen.getByRole('button', { name: 'capture' }).click();
+    });
+    expect(screen.getByTestId('can-undo').textContent).toBe('true');
+
+    act(() => {
+      screen.getByRole('button', { name: 'mutate' }).click();
+    });
+    expect(screen.getByTestId('layers').textContent).toBe('second:90');
+    expect(screen.getByTestId('viewport').textContent).toBe('9,8,2');
+
+    act(() => {
+      screen.getByRole('button', { name: 'undo' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe('first:10');
+    expect(screen.getByTestId('viewport').textContent).toBe('1,2,1');
+    expect(screen.getByTestId('dialog').textContent).toBe('active prompt');
+    expect(screen.getByTestId('inactive').textContent).toBe('archived prompt');
+    expect(screen.getByTestId('selection').textContent).toBe('first');
+    expect(screen.getByTestId('can-redo').textContent).toBe('true');
+    expect(clearDragState).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      screen.getByRole('button', { name: 'redo' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe('second:90');
+    expect(screen.getByTestId('viewport').textContent).toBe('9,8,2');
+    expect(screen.getByTestId('dialog').textContent).toBe('next prompt');
+    expect(screen.getByTestId('selection').textContent).toBe('second');
+  });
+});
diff --git a/src/components/image-editor/useCanvasHistory.ts b/src/components/image-editor/useCanvasHistory.ts
new file mode 100644
index 000000000..a9e1ae120
--- /dev/null
+++ b/src/components/image-editor/useCanvasHistory.ts
@@ -0,0 +1,155 @@
+import { type RefObject, useCallback, useRef, useState } from 'react';
+
+import { MAX_HISTORY_STEPS } from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasHistorySnapshot,
+  CanvasLayer,
+  CanvasViewport,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+
+type CanvasHistoryRefs = {
+  layersRef: RefObject<CanvasLayer[]>;
+  viewportRef: RefObject<CanvasViewport>;
+  generateDialogRef: RefObject<GenerateDialogState | null>;
+  inactiveGenerateDialogsRef: RefObject<CanvasGenerationDialogState[]>;
+  selectedLayerIdRef: RefObject<string | null>;
+  selectedLayerIdsRef: RefObject<string[]>;
+};
+
+type CanvasHistorySetters = {
+  setLayers: (layers: CanvasLayer[]) => void;
+  setViewport: (viewport: CanvasViewport) => void;
+  setGenerateDialog: (dialog: GenerateDialogState | null) => void;
+  setInactiveGenerateDialogs: (
+    dialogs: CanvasGenerationDialogState[],
+  ) => void;
+  setSelectedLayerId: (layerId: string | null) => void;
+  setSelectedLayerIds: (layerIds: string[]) => void;
+};
+
+type CanvasHistoryResetters = {
+  setHoveredLayerId: (layerId: string | null) => void;
+  setMetadataLayer: (layer: CanvasLayer | null) => void;
+  resetCanvasInteractionState: () => void;
+};
+
+function cloneGenerateDialog(dialog: GenerateDialogState): GenerateDialogState {
+  return {
+    ...dialog,
+    placeholder: dialog.placeholder ? { ...dialog.placeholder } : undefined,
+  };
+}
+
+function cloneCanvasGenerationDialog(
+  dialog: CanvasGenerationDialogState,
+): CanvasGenerationDialogState {
+  return {
+    ...dialog,
+    placeholder: dialog.placeholder ? { ...dialog.placeholder } : undefined,
+  };
+}
+
+export function useCanvasHistory({
+  refs,
+  setters,
+  resetters,
+}: {
+  refs: CanvasHistoryRefs;
+  setters: CanvasHistorySetters;
+  resetters: CanvasHistoryResetters;
+}) {
+  const undoStackRef = useRef<CanvasHistorySnapshot[]>([]);
+  const redoStackRef = useRef<CanvasHistorySnapshot[]>([]);
+  const [historyVersion, setHistoryVersion] = useState(0);
+
+  const getCanvasHistorySnapshot = useCallback(
+    (): CanvasHistorySnapshot => ({
+      layers: refs.layersRef.current.map((layer) => ({ ...layer })),
+      viewport: { ...refs.viewportRef.current },
+      generateDialog: refs.generateDialogRef.current
+        ? cloneGenerateDialog(refs.generateDialogRef.current)
+        : null,
+      inactiveGenerateDialogs:
+        refs.inactiveGenerateDialogsRef.current.map(cloneCanvasGenerationDialog),
+      selectedLayerId: refs.selectedLayerIdRef.current,
+      selectedLayerIds: [...refs.selectedLayerIdsRef.current],
+    }),
+    [refs],
+  );
+
+  const restoreCanvasHistorySnapshot = useCallback(
+    (snapshot: CanvasHistorySnapshot) => {
+      setters.setLayers(snapshot.layers.map((layer) => ({ ...layer })));
+      setters.setViewport({ ...snapshot.viewport });
+      setters.setGenerateDialog(
+        snapshot.generateDialog
+          ? cloneGenerateDialog(snapshot.generateDialog)
+          : null,
+      );
+      setters.setInactiveGenerateDialogs(
+        snapshot.inactiveGenerateDialogs.map(cloneCanvasGenerationDialog),
+      );
+      setters.setSelectedLayerId(snapshot.selectedLayerId);
+      setters.setSelectedLayerIds([...snapshot.selectedLayerIds]);
+      resetters.setHoveredLayerId(null);
+      resetters.setMetadataLayer(null);
+      resetters.resetCanvasInteractionState();
+    },
+    [resetters, setters],
+  );
+
+  const captureCanvasHistory = useCallback(
+    (options: { clearRedo?: boolean } = {}) => {
+      undoStackRef.current = [
+        ...undoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
+        getCanvasHistorySnapshot(),
+      ];
+      if (options.clearRedo !== false) {
+        redoStackRef.current = [];
+      }
+      setHistoryVersion((version) => version + 1);
+    },
+    [getCanvasHistorySnapshot],
+  );
+
+  const undoCanvasChange = useCallback(() => {
+    const previousSnapshot = undoStackRef.current.at(-1);
+    if (!previousSnapshot) {
+      return;
+    }
+    undoStackRef.current = undoStackRef.current.slice(0, -1);
+    redoStackRef.current = [
+      ...redoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
+      getCanvasHistorySnapshot(),
+    ];
+    restoreCanvasHistorySnapshot(previousSnapshot);
+    setHistoryVersion((version) => version + 1);
+  }, [getCanvasHistorySnapshot, restoreCanvasHistorySnapshot]);
+
+  const redoCanvasChange = useCallback(() => {
+    const nextSnapshot = redoStackRef.current.at(-1);
+    if (!nextSnapshot) {
+      return;
+    }
+    redoStackRef.current = redoStackRef.current.slice(0, -1);
+    undoStackRef.current = [
+      ...undoStackRef.current.slice(-(MAX_HISTORY_STEPS - 1)),
+      getCanvasHistorySnapshot(),
+    ];
+    restoreCanvasHistorySnapshot(nextSnapshot);
+    setHistoryVersion((version) => version + 1);
+  }, [getCanvasHistorySnapshot, restoreCanvasHistorySnapshot]);
+
+  return {
+    canUndo: undoStackRef.current.length > 0,
+    canRedo: redoStackRef.current.length > 0,
+    historyVersion,
+    getCanvasHistorySnapshot,
+    restoreCanvasHistorySnapshot,
+    captureCanvasHistory,
+    undoCanvasChange,
+    redoCanvasChange,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx b/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
new file mode 100644
index 000000000..6b38dcfeb
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
@@ -0,0 +1,252 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  AssetPointerDragState,
+  CanvasLayer,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import {
+  useImageCanvasAssetCanvasBridge,
+  useImageCanvasAssetLayerCleanup,
+} from './useImageCanvasAssetCanvasBridge';
+
+const defaultAsset: EditorAsset = {
+  id: 'asset-1',
+  label: '素材一',
+  src: 'data:image/png;base64,asset-1',
+  width: 320,
+  height: 240,
+  folderId: 'project',
+  sourceKind: 'uploaded',
+  sourceType: 'uploaded',
+  persisted: true,
+  assetObjectId: 'asset-object-1',
+};
+
+const defaultFolder: EditorAssetFolder = {
+  id: 'project',
+  label: '项目素材',
+  collapsed: false,
+  systemDefault: true,
+  persisted: true,
+};
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-asset-1',
+    resourceId: 'asset-object-1',
+    title: '素材一',
+    src: 'data:image/png;base64,asset-1',
+    x: 10,
+    y: 20,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    sourceAssetId: 'asset-1',
+    ...overrides,
+  };
+}
+
+function dispatchPointerEvent(
+  type: string,
+  init: MouseEventInit & { pointerId: number },
+) {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  Object.defineProperty(event, 'pointerId', { value: init.pointerId });
+  window.dispatchEvent(event);
+}
+
+function AssetCanvasBridgeHarness({
+  asset = defaultAsset,
+  resolveCanvasPoint = vi.fn(() => null),
+  appendCanvasLayersWithResources = vi.fn(),
+  captureCanvasHistory = vi.fn(),
+  selectSingleLayer = vi.fn(),
+}: {
+  asset?: EditorAsset;
+  resolveCanvasPoint?: (clientX: number, clientY: number) => {
+    x: number;
+    y: number;
+  } | null;
+  appendCanvasLayersWithResources?: (nextLayers: CanvasLayer[]) => void;
+  captureCanvasHistory?: () => void;
+  selectSingleLayer?: (layerId: string | null) => void;
+}) {
+  const assetPointerDragRef = useRef<AssetPointerDragState | null>({
+    assetId: asset.id,
+    pointerId: 7,
+    startClientX: 10,
+    startClientY: 10,
+    currentClientX: 40,
+    currentClientY: 40,
+    active: true,
+    dropFolderId: null,
+  });
+  const suppressAssetClickRef = useRef(false);
+  const layerCounterRef = useRef(0);
+  const [activeUploadFolderId, setActiveUploadFolderId] = useState('project');
+  const [hoveredLayerId, setHoveredLayerId] = useState<string | null>('hovered');
+  const [assetPointerDrag, setAssetPointerDrag] =
+    useState<AssetPointerDragState | null>(assetPointerDragRef.current);
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+
+  const bridge = useImageCanvasAssetCanvasBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets: [asset],
+    assetFolders: [defaultFolder],
+    layerCounterRef,
+    viewport: { x: 10, y: 20, scale: 2 },
+    canvasSize: { width: 900, height: 640 },
+    resolveAssetFolderId: () => null,
+    resolveCanvasPoint,
+    getCanvasDropPoint: (clientX, clientY) => ({
+      x: clientX - 10,
+      y: clientY - 20,
+    }),
+    setAssetPointerDrag,
+    setActiveUploadFolderId,
+    setUploadDropTarget,
+    setHoveredLayerId,
+    updateAssetMoveDropFolder: vi.fn(),
+    moveAssetToFolder: vi.fn(),
+    captureCanvasHistory,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    addUploadedFiles: vi.fn(),
+  });
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => bridge.addAssetLayer(asset, { x: 450, y: 320 })}
+      >
+        添加到画布
+      </button>
+      <span data-testid="folder">{activeUploadFolderId}</span>
+      <span data-testid="hover">{hoveredLayerId ?? '-'}</span>
+      <span data-testid="drag">{assetPointerDrag ? 'dragging' : 'none'}</span>
+      <span data-testid="drop-target">{uploadDropTarget ?? '-'}</span>
+    </div>
+  );
+}
+
+function AssetCleanupHarness({
+  deletedAssets = [],
+}: {
+  deletedAssets?: EditorAsset[];
+}) {
+  const [layers, setLayers] = useState([
+    createLayer({ id: 'linked', sourceAssetId: 'asset-1' }),
+    createLayer({
+      id: 'kept',
+      resourceId: 'asset-object-2',
+      src: 'data:image/png;base64,asset-2',
+      sourceAssetId: 'asset-2',
+    }),
+  ]);
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>('linked');
+  const [selectedLayerIds, setSelectedLayerIds] = useState(['linked', 'kept']);
+  const cleanup = useImageCanvasAssetLayerCleanup({
+    layers,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+  });
+
+  return (
+    <div>
+      <button type="button" onClick={() => cleanup(deletedAssets)}>
+        清理素材
+      </button>
+      <span data-testid="layers">{layers.map((layer) => layer.id).join(',')}</span>
+      <span data-testid="selected">{selectedLayerId ?? '-'}</span>
+      <span data-testid="selected-many">{selectedLayerIds.join(',')}</span>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetCanvasBridge', () => {
+  it('creates a canvas layer from an asset and clears hover state', () => {
+    const appendCanvasLayersWithResources = vi.fn();
+    const captureCanvasHistory = vi.fn();
+    const selectSingleLayer = vi.fn();
+    render(
+      <AssetCanvasBridgeHarness
+        appendCanvasLayersWithResources={appendCanvasLayersWithResources}
+        captureCanvasHistory={captureCanvasHistory}
+        selectSingleLayer={selectSingleLayer}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '添加到画布' }).click();
+    });
+
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+    expect(appendCanvasLayersWithResources).toHaveBeenCalledWith([
+      expect.objectContaining({
+        id: 'layer-asset-1-1',
+        sourceAssetId: 'asset-1',
+        x: 94,
+        y: 64,
+        width: 320,
+        height: 240,
+      }),
+    ]);
+    expect(selectSingleLayer).toHaveBeenCalledWith('layer-asset-1-1');
+    expect(screen.getByTestId('folder').textContent).toBe('project');
+    expect(screen.getByTestId('hover').textContent).toBe('-');
+  });
+
+  it('delegates active pointer drops over the canvas into the layer path', () => {
+    const appendCanvasLayersWithResources = vi.fn();
+    render(
+      <AssetCanvasBridgeHarness
+        resolveCanvasPoint={() => ({ x: 480, y: 640 })}
+        appendCanvasLayersWithResources={appendCanvasLayersWithResources}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 48,
+        clientY: 64,
+      });
+    });
+
+    expect(appendCanvasLayersWithResources).toHaveBeenCalledWith([
+      expect.objectContaining({ sourceAssetId: 'asset-1' }),
+    ]);
+    expect(screen.getByTestId('drag').textContent).toBe('none');
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+  });
+
+  it('removes canvas layers linked to deleted assets and keeps unrelated selection', () => {
+    render(<AssetCleanupHarness deletedAssets={[defaultAsset]} />);
+
+    act(() => {
+      screen.getByRole('button', { name: '清理素材' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe('kept');
+    expect(screen.getByTestId('selected').textContent).toBe('-');
+    expect(screen.getByTestId('selected-many').textContent).toBe('kept');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts b/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
new file mode 100644
index 000000000..fd93a6006
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
@@ -0,0 +1,191 @@
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+} from 'react';
+
+import {
+  createLayerFromAsset,
+  isLayerLinkedToAsset,
+} from './ImageCanvasEditorModel';
+import type {
+  AssetPointerDragState,
+  CanvasLayer,
+  CanvasViewport,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
+import { useImageCanvasCanvasDropWorkflow } from './useImageCanvasCanvasDropWorkflow';
+
+type CanvasPoint = { x: number; y: number };
+
+type UploadFilesToCanvasOptions = {
+  folderId?: string;
+  canvasPoint: CanvasPoint;
+  addToCanvas: true;
+};
+
+type UseImageCanvasAssetLayerCleanupOptions = {
+  layers: CanvasLayer[];
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  setSelectedLayerId: Dispatch<SetStateAction<string | null>>;
+  setSelectedLayerIds: Dispatch<SetStateAction<string[]>>;
+};
+
+type UseImageCanvasAssetCanvasBridgeOptions = {
+  assetPointerDragRef: RefObject<AssetPointerDragState | null>;
+  suppressAssetClickRef: RefObject<boolean>;
+  assets: EditorAsset[];
+  assetFolders: EditorAssetFolder[];
+  layerCounterRef: MutableRefObject<number>;
+  viewport: CanvasViewport;
+  canvasSize: { width: number; height: number };
+  resolveAssetFolderId: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint: (clientX: number, clientY: number) => CanvasPoint | null;
+  getCanvasDropPoint: (clientX: number, clientY: number) => CanvasPoint;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setActiveUploadFolderId: Dispatch<SetStateAction<string>>;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setHoveredLayerId: Dispatch<SetStateAction<string | null>>;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  captureCanvasHistory: () => void;
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  addUploadedFiles: (
+    files: FileList | File[],
+    options: UploadFilesToCanvasOptions,
+  ) => void;
+};
+
+export function useImageCanvasAssetLayerCleanup({
+  layers,
+  setLayers,
+  setSelectedLayerId,
+  setSelectedLayerIds,
+}: UseImageCanvasAssetLayerCleanupOptions) {
+  return useCallback(
+    (deletedAssets: EditorAsset[]) => {
+      if (!deletedAssets.length) {
+        return;
+      }
+      setLayers((currentLayers) =>
+        currentLayers.filter(
+          (layer) =>
+            !deletedAssets.some((asset) => isLayerLinkedToAsset(layer, asset)),
+        ),
+      );
+      setSelectedLayerIds((currentIds) =>
+        currentIds.filter((layerId) =>
+          layers.every(
+            (layer) =>
+              layer.id !== layerId ||
+              !deletedAssets.some((asset) =>
+                isLayerLinkedToAsset(layer, asset),
+              ),
+          ),
+        ),
+      );
+      setSelectedLayerId((currentId) => {
+        if (!currentId) {
+          return currentId;
+        }
+        const currentLayer = layers.find((layer) => layer.id === currentId);
+        return currentLayer &&
+          deletedAssets.some((asset) => isLayerLinkedToAsset(currentLayer, asset))
+          ? null
+          : currentId;
+      });
+    },
+    [layers, setLayers, setSelectedLayerId, setSelectedLayerIds],
+  );
+}
+
+export function useImageCanvasAssetCanvasBridge({
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  assets,
+  assetFolders,
+  layerCounterRef,
+  viewport,
+  canvasSize,
+  resolveAssetFolderId,
+  resolveCanvasPoint,
+  getCanvasDropPoint,
+  setAssetPointerDrag,
+  setActiveUploadFolderId,
+  setUploadDropTarget,
+  setHoveredLayerId,
+  updateAssetMoveDropFolder,
+  moveAssetToFolder,
+  captureCanvasHistory,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+  addUploadedFiles,
+}: UseImageCanvasAssetCanvasBridgeOptions) {
+  const addAssetLayer = useCallback(
+    (asset: EditorAsset, position?: CanvasPoint) => {
+      setActiveUploadFolderId(asset.folderId);
+      layerCounterRef.current += 1;
+      const nextLayer = createLayerFromAsset(
+        asset,
+        layerCounterRef.current,
+        viewport,
+        {
+          x: position?.x ?? canvasSize.width / 2,
+          y: position?.y ?? canvasSize.height / 2,
+        },
+      );
+      captureCanvasHistory();
+      appendCanvasLayersWithResources([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setHoveredLayerId(null);
+    },
+    [
+      appendCanvasLayersWithResources,
+      canvasSize.height,
+      canvasSize.width,
+      captureCanvasHistory,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveUploadFolderId,
+      setHoveredLayerId,
+      viewport,
+    ],
+  );
+
+  useImageCanvasAssetPointerDragBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  const canvasDropWorkflow = useImageCanvasCanvasDropWorkflow({
+    assets,
+    assetFolders,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    getCanvasDropPoint,
+    addAssetLayer,
+    addUploadedFiles,
+  });
+
+  return useMemo(
+    () => ({
+      addAssetLayer,
+      ...canvasDropWorkflow,
+    }),
+    [addAssetLayer, canvasDropWorkflow],
+  );
+}
diff --git a/src/components/image-editor/useImageCanvasAssetExportWorkflow.test.tsx b/src/components/image-editor/useImageCanvasAssetExportWorkflow.test.tsx
new file mode 100644
index 000000000..795a98e5a
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetExportWorkflow.test.tsx
@@ -0,0 +1,246 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import JSZip from 'jszip';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetExportWorkflow } from './useImageCanvasAssetExportWorkflow';
+
+function createLayer(
+  id: string,
+  overrides: Partial<CanvasLayer> = {},
+): CanvasLayer {
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${btoa(`layer-${id.replace(/[^\w-]/gu, '-')}`)}`,
+    x: 10,
+    y: 20,
+    width: 100,
+    height: 80,
+    originalWidth: 100,
+    originalHeight: 80,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+async function readZipText(zip: JSZip, path: string) {
+  const file = zip.file(path);
+  if (!file) {
+    throw new Error(`Missing zip file: ${path}`);
+  }
+  return file.async('text');
+}
+
+function ExportWorkflowHarness({ layers }: { layers: CanvasLayer[] }) {
+  const workflow = useImageCanvasAssetExportWorkflow({
+    layers,
+    projectId: 'project-export',
+    projectTitle: '导出项目',
+  });
+
+  return (
+    <div>
+      <span data-testid="exporting">{String(workflow.isExportingAssets)}</span>
+      <span data-testid="status">
+        {workflow.assetExportStatus
+          ? `${workflow.assetExportStatus.tone}:${workflow.assetExportStatus.message}`
+          : '-'}
+      </span>
+      <button
+        type="button"
+        onClick={() => {
+          void workflow.exportCanvasAssets();
+        }}
+      >
+        导出画布素材
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.exportLayerImage(layers[0] ?? null)}
+      >
+        导出单图
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetExportWorkflow', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('exports canvas assets into a zip with metadata and failed image records', async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async (url: string) => {
+      if (url === '/generated-ok.png') {
+        return new Response(new Blob(['generated'], { type: 'image/png' }));
+      }
+      if (url === '/generated-video.mp4') {
+        return new Response(new Blob(['video'], { type: 'video/mp4' }));
+      }
+      return new Response(null, { status: 404 });
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+    let exportedBlob: Blob | null = null;
+    let downloadName = '';
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: vi.fn((blob: Blob) => {
+        exportedBlob = blob;
+        return 'blob:editor-export';
+      }),
+    });
+    Object.defineProperty(URL, 'revokeObjectURL', {
+      configurable: true,
+      value: vi.fn(),
+    });
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(
+      function click(this: HTMLAnchorElement) {
+        downloadName = this.download;
+      },
+    );
+
+    try {
+      render(
+        <ExportWorkflowHarness
+          layers={[
+            createLayer('asset-a', {
+              title: '素材 A',
+              sourceAssetId: 'asset-a',
+              zIndex: 1,
+              hidden: true,
+              locked: true,
+              flipX: true,
+            }),
+            createLayer('asset-a-duplicate', {
+              title: '素材 A 副本',
+              sourceAssetId: 'asset-a',
+              zIndex: 2,
+            }),
+            createLayer('generated', {
+              title: '生成图',
+              src: '/generated-ok.png',
+              sourceType: 'generated',
+              prompt: '明亮主视觉',
+              zIndex: 3,
+            }),
+            createLayer('video', {
+              title: '生成视频',
+              src: '/generated-video.mp4',
+              mediaType: 'video',
+              sourceType: 'generated',
+              zIndex: 4,
+            }),
+            createLayer('audio', {
+              title: '胜利音效',
+              src: 'data:audio/wav;base64,YXVkaW8=',
+              mediaType: 'audio',
+              objectKey: 'generated-audio.wav',
+              sourceType: 'generated',
+              zIndex: 5,
+            }),
+            createLayer('failed', {
+              title: '失败图',
+              src: '/missing.png',
+              zIndex: 6,
+            }),
+          ]}
+        />,
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: '导出画布素材' }));
+
+      await waitFor(() => {
+        expect(exportedBlob).toBeTruthy();
+      });
+      expect(downloadName).toMatch(/^导出项目-画布素材-\d{8}\.zip$/u);
+
+      const zip = await JSZip.loadAsync(exportedBlob!);
+      expect(zip.file('导出项目-画布素材/images/001-素材 A.png')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/images/002-生成图.png')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/media/003-生成视频.mp4')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/media/004-胜利音效.wav')).toBeTruthy();
+      expect(zip.file('导出项目-画布素材/images/005-失败图.png')).toBeNull();
+
+      const metadata = JSON.parse(
+        await readZipText(zip, '导出项目-画布素材/metadata.json'),
+      );
+      expect(metadata.projectId).toBe('project-export');
+      expect(metadata.layers).toHaveLength(6);
+      expect(metadata.layers[0].file).toBe('images/001-素材 A.png');
+      expect(metadata.layers[1].file).toBe('images/001-素材 A.png');
+      expect(metadata.layers[2].mediaType).toBe('image');
+      expect(metadata.layers[0].canvas.hidden).toBe(true);
+      expect(metadata.layers[0].canvas.locked).toBe(true);
+      expect(metadata.layers[0].canvas.flipX).toBe(true);
+      expect(metadata.layers[2].sourceType).toBe('generated');
+      expect(metadata.layers[2].prompt).toBe('明亮主视觉');
+      expect(metadata.layers[3].file).toBe('media/003-生成视频.mp4');
+      expect(metadata.layers[3].mediaType).toBe('video');
+      expect(metadata.layers[4].file).toBe('media/004-胜利音效.wav');
+      expect(metadata.layers[4].mediaType).toBe('audio');
+      expect(metadata.layers[5].file).toBeNull();
+      expect(metadata.layers[5].exportError).toContain('404');
+      expect(metadata.failedImages).toHaveLength(1);
+      expect(
+        await readZipText(zip, '导出项目-画布素材/manifest.txt'),
+      ).toContain('失败素材数量：1');
+      expect(screen.getByTestId('status').textContent).toBe(
+        'error:部分素材未能导出',
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+      delete (URL as unknown as { createObjectURL?: unknown }).createObjectURL;
+      delete (URL as unknown as { revokeObjectURL?: unknown }).revokeObjectURL;
+    }
+  });
+
+  it('reports empty exports and supports direct layer image downloads', async () => {
+    let downloadName = '';
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(
+      function click(this: HTMLAnchorElement) {
+        downloadName = this.download;
+      },
+    );
+    render(
+      <ExportWorkflowHarness
+        layers={[createLayer('single-export', { title: '单图/导出:*?' })]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '导出单图' }));
+
+    expect(downloadName).toBe('单图 导出.png');
+
+    render(
+      <ExportWorkflowHarness
+        layers={[
+          createLayer('single-video-export', {
+            title: '视频导出',
+            src: '/generated/video.webm?token=1',
+            mediaType: 'video',
+          }),
+        ]}
+      />,
+    );
+    fireEvent.click(screen.getAllByRole('button', { name: '导出单图' }).at(-1)!);
+
+    expect(downloadName).toBe('视频导出.webm');
+
+    render(<ExportWorkflowHarness layers={[]} />);
+    fireEvent.click(
+      screen.getAllByRole('button', { name: '导出画布素材' }).at(-1)!,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId('status').at(-1)?.textContent).toBe(
+        'info:当前画布没有可导出的素材',
+      );
+    });
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts b/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
new file mode 100644
index 000000000..515c0d4a4
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
@@ -0,0 +1,227 @@
+import JSZip from 'jszip';
+import { useCallback, useState } from 'react';
+
+import type {
+  CanvasAssetExportImage,
+  CanvasAssetExportMetadata,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  blobToUint8Array,
+  buildLayerExportMetadata,
+  formatExportDate,
+  getLayerAssetExtensionFromTypeOrSrc,
+  getLayerExportKey,
+  readLayerAssetBlob,
+  sanitizeExportFilePart,
+} from './ImageCanvasExportModel';
+
+export type AssetExportStatus = {
+  tone: 'info' | 'success' | 'error';
+  message: string;
+};
+
+type UseImageCanvasAssetExportWorkflowOptions = {
+  layers: CanvasLayer[];
+  projectId: string | null;
+  projectTitle: string;
+};
+
+export function useImageCanvasAssetExportWorkflow({
+  layers,
+  projectId,
+  projectTitle,
+}: UseImageCanvasAssetExportWorkflowOptions) {
+  const [assetExportStatus, setAssetExportStatus] =
+    useState<AssetExportStatus | null>(null);
+  const [isExportingAssets, setIsExportingAssets] = useState(false);
+
+  const exportLayerImage = useCallback((layer: CanvasLayer | null) => {
+    if (!layer) {
+      return;
+    }
+    const link = document.createElement('a');
+    link.href = layer.src;
+    const extension = getLayerAssetExtensionFromTypeOrSrc(
+      layer.mediaType ?? 'image',
+      '',
+      layer.objectKey ?? layer.src,
+    );
+    link.download = `${sanitizeExportFilePart(
+      layer.title,
+      'canvas-layer',
+    )}.${extension}`;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+  }, []);
+
+  const exportCanvasAssets = useCallback(async () => {
+    if (isExportingAssets) {
+      return;
+    }
+    const exportableLayers = layers
+      .filter((layer) => layer.src.trim().length > 0)
+      .sort((left, right) => left.zIndex - right.zIndex);
+    if (!exportableLayers.length) {
+      setAssetExportStatus({
+        tone: 'info',
+        message: '当前画布没有可导出的素材',
+      });
+      return;
+    }
+
+    setIsExportingAssets(true);
+    setAssetExportStatus(null);
+
+    try {
+      const exportedAt = new Date();
+      const projectName = sanitizeExportFilePart(projectTitle, '未命名画布');
+      const rootFolderName = `${projectName}-画布素材`;
+      const zip = new JSZip();
+      const rootFolder = zip.folder(rootFolderName) ?? zip;
+      const imagesFolder = rootFolder.folder('images') ?? rootFolder;
+      const mediaFolder = rootFolder.folder('media') ?? rootFolder;
+      const imageByKey = new Map<string, CanvasAssetExportImage>();
+      const usedFileNames = new Map<string, number>();
+
+      for (const layer of exportableLayers) {
+        const key = getLayerExportKey(layer);
+        if (imageByKey.has(key)) {
+          continue;
+        }
+        const index = imageByKey.size + 1;
+        const safeTitle = sanitizeExportFilePart(layer.title, '画布素材');
+        const baseFileName = `${String(index).padStart(3, '0')}-${safeTitle}`;
+        const duplicateCount = usedFileNames.get(baseFileName) ?? 0;
+        usedFileNames.set(baseFileName, duplicateCount + 1);
+        const indexedFileName =
+          duplicateCount > 0
+            ? `${baseFileName}-${duplicateCount + 1}`
+            : baseFileName;
+
+        try {
+          const blob = await readLayerAssetBlob(layer);
+          const mediaType = layer.mediaType ?? 'image';
+          const extension = getLayerAssetExtensionFromTypeOrSrc(
+            mediaType,
+            blob.type,
+            layer.objectKey ?? layer.src,
+          );
+          const folderName = mediaType === 'image' ? 'images' : 'media';
+          const targetFolder = mediaType === 'image' ? imagesFolder : mediaFolder;
+          const file = `${folderName}/${indexedFileName}.${extension}`;
+          imageByKey.set(key, {
+            key,
+            file,
+            layer,
+            blob,
+          });
+          targetFolder.file(
+            `${indexedFileName}.${extension}`,
+            await blobToUint8Array(blob),
+          );
+        } catch (error) {
+          const mediaType = layer.mediaType ?? 'image';
+          const extension = getLayerAssetExtensionFromTypeOrSrc(
+            mediaType,
+            '',
+            layer.objectKey ?? layer.src,
+          );
+          const folderName = mediaType === 'image' ? 'images' : 'media';
+          imageByKey.set(key, {
+            key,
+            file: `${folderName}/${indexedFileName}.${extension}`,
+            layer,
+            error: error instanceof Error ? error.message : '素材读取失败',
+          });
+        }
+      }
+
+      const failedImages = [...imageByKey.values()].filter(
+        (image) => image.error,
+      );
+      const successfulImages = [...imageByKey.values()].filter(
+        (image) => image.blob,
+      );
+      if (!successfulImages.length) {
+        setAssetExportStatus({
+          tone: 'error',
+          message: '素材导出失败',
+        });
+        return;
+      }
+
+      const metadata: CanvasAssetExportMetadata = {
+        projectId,
+        projectTitle,
+        exportedAt: exportedAt.toISOString(),
+        layers: exportableLayers.map((layer) => {
+          const image = imageByKey.get(getLayerExportKey(layer));
+          return buildLayerExportMetadata(
+            layer,
+            image?.blob ? image.file : null,
+            image?.error,
+          );
+        }),
+        failedImages: failedImages.map((image) => ({
+          key: image.key,
+          title: image.layer.title,
+          src: image.layer.src,
+          error: image.error ?? '素材读取失败',
+        })),
+      };
+      const manifest = [
+        `项目：${projectTitle}`,
+        `导出时间：${metadata.exportedAt}`,
+        `素材数量：${successfulImages.length}`,
+        `图层数量：${exportableLayers.length}`,
+        failedImages.length ? `失败素材数量：${failedImages.length}` : null,
+      ]
+        .filter(Boolean)
+        .join('\n');
+
+      rootFolder.file('metadata.json', JSON.stringify(metadata, null, 2));
+      rootFolder.file('manifest.txt', manifest);
+
+      const zipBlob = await zip.generateAsync({ type: 'blob' });
+      if (
+        typeof URL.createObjectURL !== 'function' ||
+        typeof URL.revokeObjectURL !== 'function'
+      ) {
+        setAssetExportStatus({
+          tone: 'error',
+          message: '当前浏览器不支持素材下载',
+        });
+        return;
+      }
+
+      const downloadUrl = URL.createObjectURL(zipBlob);
+      const link = document.createElement('a');
+      link.href = downloadUrl;
+      link.download = `${rootFolderName}-${formatExportDate(exportedAt)}.zip`;
+      document.body.appendChild(link);
+      link.click();
+      link.remove();
+      URL.revokeObjectURL(downloadUrl);
+      setAssetExportStatus({
+        tone: failedImages.length ? 'error' : 'success',
+        message: failedImages.length ? '部分素材未能导出' : '画布素材已导出',
+      });
+    } catch {
+      setAssetExportStatus({
+        tone: 'error',
+        message: '素材导出失败',
+      });
+    } finally {
+      setIsExportingAssets(false);
+    }
+  }, [isExportingAssets, layers, projectId, projectTitle]);
+
+  return {
+    assetExportStatus,
+    isExportingAssets,
+    exportCanvasAssets,
+    exportLayerImage,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx b/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx
new file mode 100644
index 000000000..7f6a7c084
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetLibrary.test.tsx
@@ -0,0 +1,404 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { useRef } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import type { EditorAssetSnapshot } from '../../services/image-editor/editorProjectClient';
+import type { EditorAsset } from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetLibrary } from './useImageCanvasAssetLibrary';
+
+const createEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetMock = vi.hoisted(() => vi.fn());
+const deleteEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+const loadEditorAssetLibraryMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetMock = vi.hoisted(() => vi.fn());
+const updateEditorAssetFolderMock = vi.hoisted(() => vi.fn());
+
+const defaultOpenEditorLoginModal = () => {};
+const defaultOnDeleteAssets = () => {};
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    createEditorAssetFolder: createEditorAssetFolderMock,
+    deleteEditorAsset: deleteEditorAssetMock,
+    deleteEditorAssetFolder: deleteEditorAssetFolderMock,
+    loadEditorAssetLibrary: loadEditorAssetLibraryMock,
+    updateEditorAsset: updateEditorAssetMock,
+    updateEditorAssetFolder: updateEditorAssetFolderMock,
+  };
+});
+
+function createUploadedAsset(overrides: Partial<EditorAsset> = {}): EditorAsset {
+  return {
+    id: 'asset-a',
+    label: '素材A',
+    src: 'data:image/png;base64,YQ==',
+    width: 320,
+    height: 240,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+    ...overrides,
+  };
+}
+
+function createAssetSnapshot(
+  overrides: Partial<EditorAssetSnapshot> = {},
+): EditorAssetSnapshot {
+  return {
+    assetId: 'asset-a',
+    label: '素材A',
+    imageSrc: 'data:image/png;base64,YQ==',
+    width: 320,
+    height: 240,
+    folderId: 'project',
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function AssetLibraryHarness({
+  canAccessProtectedData = true,
+  openEditorLoginModal = defaultOpenEditorLoginModal,
+  onDeleteAssets = defaultOnDeleteAssets,
+}: {
+  canAccessProtectedData?: boolean;
+  openEditorLoginModal?: (postLoginAction?: (() => void) | null) => void;
+  onDeleteAssets?: (assets: EditorAsset[]) => void;
+}) {
+  const assetListRef = useRef<HTMLDivElement | null>(null);
+  const assetLibrary = useImageCanvasAssetLibrary({
+    assetListRef,
+    canAccessProtectedData,
+    openEditorLoginModal,
+    onDeleteAssets,
+  });
+
+  return (
+    <div>
+      <div ref={assetListRef}>
+        {assetLibrary.groupedAssets.map((folder) => (
+          <section key={folder.id} data-asset-folder-id={folder.id}>
+            <h2>{folder.label}</h2>
+            {folder.assets.map((asset, index) => (
+              <button
+                key={asset.id || `asset-${index}`}
+                type="button"
+                data-asset-id={asset.id}
+                onClick={() => assetLibrary.toggleAssetSelected(asset.id)}
+              >
+                {asset.label}
+              </button>
+            ))}
+          </section>
+        ))}
+      </div>
+      <span data-testid="folders">
+        {assetLibrary.assetFolders
+          .map((folder) => `${folder.id}:${folder.label}:${folder.persisted}`)
+          .join('|')}
+      </span>
+      <span data-testid="assets">
+        {assetLibrary.assets
+          .map((asset) => `${asset.id}:${asset.label}:${asset.folderId}`)
+          .join('|')}
+      </span>
+      <span data-testid="active-upload-folder">
+        {assetLibrary.activeUploadFolderId}
+      </span>
+      <span data-testid="all-selected">
+        {String(assetLibrary.allSelectableAssetsSelected)}
+      </span>
+      <span data-testid="selected-assets">
+        {[...assetLibrary.selectedAssetIds].join('|')}
+      </span>
+      <span data-testid="new-folder-name">{assetLibrary.newFolderName}</span>
+      <button
+        type="button"
+        onClick={() => {
+          assetLibrary.setNewFolderName('角色素材');
+          assetLibrary.setCreatingFolder(true);
+        }}
+      >
+        prepare folder
+      </button>
+      <button
+        type="button"
+        onClick={() => void assetLibrary.commitNewAssetFolder()}
+      >
+        commit folder
+      </button>
+      <button
+        type="button"
+        onClick={() => assetLibrary.moveAssetToFolder('asset-a', 'folder-role')}
+      >
+        move asset
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const target = assetLibrary.assets.find(
+            (asset) => asset.id === 'asset-a',
+          );
+          if (target) {
+            assetLibrary.deleteUploadedAsset(target);
+          }
+        }}
+      >
+        delete asset
+      </button>
+      <button type="button" onClick={assetLibrary.toggleAllAssetsSelected}>
+        toggle all
+      </button>
+      <button type="button" onClick={assetLibrary.deleteSelectedAssets}>
+        delete selected
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetLibrary', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadEditorAssetLibraryMock.mockResolvedValue({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [createAssetSnapshot()],
+    });
+    createEditorAssetFolderMock.mockResolvedValue({
+      folderId: 'folder-role',
+      label: '角色素材',
+      collapsed: false,
+      systemDefault: false,
+    });
+    updateEditorAssetMock.mockResolvedValue(createAssetSnapshot());
+    deleteEditorAssetMock.mockResolvedValue(createAssetSnapshot());
+    deleteEditorAssetFolderMock.mockResolvedValue({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [],
+    });
+    updateEditorAssetFolderMock.mockResolvedValue({
+      folderId: 'project',
+      label: '项目素材',
+      collapsed: false,
+      systemDefault: true,
+    });
+  });
+
+  it('loads and normalizes the account asset library', async () => {
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'project-duplicate',
+          label: '重复默认',
+          sortOrder: 1,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [createAssetSnapshot()],
+    });
+
+    render(<AssetLibraryHarness />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('folders').textContent).toBe(
+        'project:项目素材:true',
+      );
+    });
+    expect(screen.getByTestId('assets').textContent).toBe(
+      'asset-a:素材A:project',
+    );
+    expect(screen.getByTestId('active-upload-folder').textContent).toBe(
+      'project',
+    );
+  });
+
+  it('opens login when loading the asset library is unauthorized', async () => {
+    const openEditorLoginModal = vi.fn();
+    loadEditorAssetLibraryMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+
+    render(
+      <AssetLibraryHarness openEditorLoginModal={openEditorLoginModal} />,
+    );
+
+    await waitFor(() => {
+      expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('does not request the protected asset library before login is available', () => {
+    render(<AssetLibraryHarness canAccessProtectedData={false} />);
+
+    expect(loadEditorAssetLibraryMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('folders').textContent).toBe(
+      'project:项目素材:false',
+    );
+  });
+
+  it('creates a local folder and replaces it with the persisted folder id', async () => {
+    let resolveCreateFolder: (
+      folder: Awaited<ReturnType<typeof createEditorAssetFolderMock>>,
+    ) => void = () => {};
+    createEditorAssetFolderMock.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveCreateFolder = resolve;
+      }),
+    );
+    render(<AssetLibraryHarness />);
+
+    await screen.findByText('素材A');
+    act(() => screen.getByRole('button', { name: 'prepare folder' }).click());
+    await waitFor(() => {
+      expect(screen.getByTestId('new-folder-name').textContent).toBe(
+        '角色素材',
+      );
+    });
+    act(() => screen.getByRole('button', { name: 'commit folder' }).click());
+    await waitFor(() => {
+      expect(screen.getByTestId('folders').textContent).toContain(
+        'folder-',
+      );
+    });
+    act(() => {
+      resolveCreateFolder({
+        folderId: 'folder-role',
+        label: '角色素材',
+        collapsed: false,
+        systemDefault: false,
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('folders').textContent).toContain(
+        'folder-role:角色素材:true',
+      );
+    });
+    expect(createEditorAssetFolderMock).toHaveBeenCalledWith('角色素材', 101);
+    expect(screen.getByTestId('active-upload-folder').textContent).toBe(
+      'folder-role',
+    );
+  });
+
+  it('moves a persisted asset to another folder', async () => {
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+        {
+          folderId: 'folder-role',
+          label: '角色素材',
+          sortOrder: 1,
+          collapsed: false,
+          systemDefault: false,
+        },
+      ],
+      assets: [createAssetSnapshot()],
+    });
+
+    render(<AssetLibraryHarness />);
+
+    await screen.findByText('素材A');
+    act(() => screen.getByRole('button', { name: 'move asset' }).click());
+
+    expect(screen.getByTestId('assets').textContent).toBe(
+      'asset-a:素材A:folder-role',
+    );
+    expect(updateEditorAssetMock).toHaveBeenCalledWith('asset-a', {
+      folderId: 'folder-role',
+    });
+  });
+
+  it('deletes uploaded assets and reports them to the canvas cleanup callback', async () => {
+    const onDeleteAssets = vi.fn();
+    render(<AssetLibraryHarness onDeleteAssets={onDeleteAssets} />);
+
+    await screen.findByText('素材A');
+    act(() => screen.getByRole('button', { name: 'delete asset' }).click());
+
+    expect(screen.getByTestId('assets').textContent).toBe('');
+    expect(onDeleteAssets).toHaveBeenCalledWith([
+      expect.objectContaining({ id: 'asset-a' }),
+    ]);
+    expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-a');
+  });
+
+  it('selects and deletes selected uploaded assets', async () => {
+    const onDeleteAssets = vi.fn();
+    loadEditorAssetLibraryMock.mockResolvedValueOnce({
+      folders: [
+        {
+          folderId: 'project',
+          label: '项目素材',
+          sortOrder: 0,
+          collapsed: false,
+          systemDefault: true,
+        },
+      ],
+      assets: [
+        createAssetSnapshot({ assetId: 'asset-a', label: '素材A' }),
+        createAssetSnapshot({ assetId: 'asset-b', label: '素材B' }),
+      ],
+    });
+
+    render(<AssetLibraryHarness onDeleteAssets={onDeleteAssets} />);
+
+    await screen.findByText('素材A');
+    act(() => screen.getByRole('button', { name: 'toggle all' }).click());
+    expect(screen.getByTestId('all-selected').textContent).toBe('true');
+    act(() => screen.getByRole('button', { name: '素材B' }).click());
+    await waitFor(() => {
+      expect(screen.getByTestId('selected-assets').textContent).toBe('asset-a');
+    });
+    act(() => screen.getByRole('button', { name: 'delete selected' }).click());
+
+    expect(screen.getByTestId('assets').textContent).toBe(
+      'asset-b:素材B:project',
+    );
+    expect(onDeleteAssets).toHaveBeenCalledWith([
+      expect.objectContaining({ id: 'asset-a' }),
+    ]);
+    expect(deleteEditorAssetMock).toHaveBeenCalledWith('asset-a');
+    expect(deleteEditorAssetMock).not.toHaveBeenCalledWith('asset-b');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasAssetLibrary.ts b/src/components/image-editor/useImageCanvasAssetLibrary.ts
new file mode 100644
index 000000000..38eb96380
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetLibrary.ts
@@ -0,0 +1,579 @@
+import {
+  type Dispatch,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import { ApiClientError } from '../../services/apiClient';
+import {
+  createEditorAssetFolder,
+  deleteEditorAsset,
+  deleteEditorAssetFolder,
+  loadEditorAssetLibrary,
+  updateEditorAsset,
+  updateEditorAssetFolder,
+} from '../../services/image-editor/editorProjectClient';
+import {
+  EDITOR_ASSET_FOLDERS,
+  escapeCssIdentifier,
+  normalizeAssetLibrary,
+} from './ImageCanvasEditorModel';
+import {
+  areAllSelectableAssetsSelected,
+  createAssetMarqueeFromPointer,
+  createAssetMarqueeSelectionRect,
+  createLocalAssetFolder,
+  deleteAssetFolderLocally,
+  getSelectableAssets,
+  groupAssetsByFolder,
+  moveAssetToFolderLocally,
+  moveAssetMarqueeToPointer,
+  removeAssetById,
+  removeSelectedAssets,
+  renameAssetById,
+  renameAssetFolderById,
+  replaceLocalAssetFolder,
+  resolveAllAssetSelection,
+  resolveDefaultAssetFolder,
+  resolveAssetFolderIdFromPoint,
+  resolvePinnedAssetMoveFolderId,
+  selectUploadedAssetsInRect,
+  shouldStartAssetMarquee,
+  toggleAssetFolderCollapsed,
+  toggleAssetSelection,
+} from './ImageCanvasAssetLibraryModel';
+import type {
+  AssetMarqueeState,
+  AssetPointerDragState,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+export { readImageFileAsDataUrl } from './ImageCanvasFileModel';
+
+function isEditorAuthError(error: unknown) {
+  return (
+    error instanceof ApiClientError &&
+    (error.status === 401 || error.status === 403)
+  );
+}
+
+const ASSET_FOLDER_SELECTOR = '[data-asset-folder-id]';
+const ASSET_ITEM_SELECTOR = '[data-asset-id]';
+const ASSET_MARQUEE_BLOCKED_TARGET_SELECTOR =
+  'button, input, textarea, select, [data-asset-id]';
+
+function readAssetFolderHitTargets(listElement: ParentNode | null) {
+  return [
+    ...(listElement?.querySelectorAll<HTMLElement>(ASSET_FOLDER_SELECTOR) ?? []),
+  ]
+    .map((element) => {
+      const folderId = element.dataset.assetFolderId;
+      return folderId
+        ? {
+            folderId,
+            rect: element.getBoundingClientRect(),
+          }
+        : null;
+    })
+    .filter((target): target is NonNullable<typeof target> => Boolean(target));
+}
+
+function readAssetHitTargets(listElement: ParentNode | null) {
+  return [
+    ...(listElement?.querySelectorAll<HTMLElement>(ASSET_ITEM_SELECTOR) ?? []),
+  ]
+    .map((element) => {
+      const assetId = element.dataset.assetId;
+      return assetId
+        ? {
+            assetId,
+            rect: element.getBoundingClientRect(),
+          }
+        : null;
+    })
+    .filter((target): target is NonNullable<typeof target> => Boolean(target));
+}
+
+export function useImageCanvasAssetLibrary({
+  assetListRef,
+  canAccessProtectedData,
+  openEditorLoginModal,
+  onDeleteAssets,
+}: {
+  assetListRef: RefObject<HTMLDivElement | null>;
+  canAccessProtectedData: boolean;
+  openEditorLoginModal: (postLoginAction?: (() => void) | null) => void;
+  onDeleteAssets?: (assets: EditorAsset[]) => void;
+}) {
+  const [assetFolders, setAssetFolders] =
+    useState<EditorAssetFolder[]>(EDITOR_ASSET_FOLDERS);
+  const [assets, setAssets] = useState<EditorAsset[]>([]);
+  const [renamingAsset, setRenamingAsset] = useState<{
+    assetId: string;
+    value: string;
+  } | null>(null);
+  const [renamingFolder, setRenamingFolder] = useState<{
+    folderId: string;
+    value: string;
+  } | null>(null);
+  const [creatingFolder, setCreatingFolder] = useState(false);
+  const [newFolderName, setNewFolderName] = useState('');
+  const [activeUploadFolderId, setActiveUploadFolderId] = useState('project');
+  const [isAssetSelectionMode, setIsAssetSelectionMode] = useState(false);
+  const [selectedAssetIds, setSelectedAssetIds] = useState<Set<string>>(
+    () => new Set(),
+  );
+  const [assetMarquee, setAssetMarquee] = useState<AssetMarqueeState | null>(
+    null,
+  );
+  const [assetPointerDrag, setAssetPointerDrag] =
+    useState<AssetPointerDragState | null>(null);
+  const [assetMoveDropFolderId, setAssetMoveDropFolderId] = useState<
+    string | null
+  >(null);
+  const [pinnedAssetMoveFolderId, setPinnedAssetMoveFolderId] = useState<
+    string | null
+  >(null);
+
+  const groupedAssets = useMemo(
+    () => groupAssetsByFolder(assetFolders, assets),
+    [assetFolders, assets],
+  );
+  const selectableAssets = useMemo(
+    () => getSelectableAssets(assets),
+    [assets],
+  );
+  const allSelectableAssetsSelected = areAllSelectableAssetsSelected(
+    selectableAssets,
+    selectedAssetIds,
+  );
+
+  useEffect(() => {
+    if (!canAccessProtectedData) {
+      return undefined;
+    }
+    let cancelled = false;
+    loadEditorAssetLibrary()
+      .then((library) => {
+        if (cancelled) {
+          return;
+        }
+        const nextLibrary = normalizeAssetLibrary(library);
+        setAssetFolders(nextLibrary.folders);
+        setAssets(nextLibrary.assets);
+        const defaultFolder = nextLibrary.folders.find(
+          (folder) => folder.systemDefault,
+        );
+        setActiveUploadFolderId(
+          defaultFolder?.id ?? nextLibrary.folders[0]?.id ?? 'project',
+        );
+      })
+      .catch((error: unknown) => {
+        if (!cancelled && isEditorAuthError(error)) {
+          openEditorLoginModal();
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [canAccessProtectedData, openEditorLoginModal]);
+
+  const resolveAssetFolderId = useCallback(
+    (clientX: number, clientY: number) => {
+      const listElement = assetListRef.current;
+      if (!listElement) {
+        return null;
+      }
+      return resolveAssetFolderIdFromPoint({
+        point: { clientX, clientY },
+        listRect: listElement.getBoundingClientRect(),
+        folders: readAssetFolderHitTargets(listElement),
+      });
+    },
+    [assetListRef],
+  );
+
+  const updateAssetMoveDropFolder = useCallback(
+    (folderId: string | null) => {
+      setAssetMoveDropFolderId(folderId);
+      if (!folderId) {
+        setPinnedAssetMoveFolderId(null);
+        return;
+      }
+      const listElement = assetListRef.current;
+      const header = listElement?.querySelector<HTMLElement>(
+        `[data-asset-folder-header-id="${escapeCssIdentifier(folderId)}"]`,
+      );
+      setPinnedAssetMoveFolderId(
+        resolvePinnedAssetMoveFolderId({
+          folderId,
+          listRect: listElement?.getBoundingClientRect(),
+          headerRect: header?.getBoundingClientRect(),
+        }),
+      );
+    },
+    [assetListRef],
+  );
+
+  const startRenamingAsset = useCallback((asset: EditorAsset) => {
+    setRenamingAsset({
+      assetId: asset.id,
+      value: asset.label,
+    });
+  }, []);
+
+  const commitAssetRename = useCallback(
+    (asset: EditorAsset) => {
+      const nextLabel = renamingAsset?.value.trim();
+      if (!nextLabel) {
+        setRenamingAsset(null);
+        return;
+      }
+      setAssets((currentAssets) =>
+        renameAssetById(currentAssets, asset.id, nextLabel),
+      );
+      if (asset.persisted) {
+        updateEditorAsset(asset.id, { label: nextLabel }).catch(() => {});
+      }
+      setRenamingAsset(null);
+    },
+    [renamingAsset],
+  );
+
+  const toggleAssetFolder = useCallback(
+    (folderId: string) => {
+      const nextFolder = assetFolders.find((folder) => folder.id === folderId);
+      const nextCollapsed = !(nextFolder?.collapsed ?? false);
+      setAssetFolders((currentFolders) =>
+        toggleAssetFolderCollapsed(currentFolders, folderId),
+      );
+      if (nextFolder?.persisted) {
+        updateEditorAssetFolder(folderId, { collapsed: nextCollapsed }).catch(
+          () => {},
+        );
+      }
+    },
+    [assetFolders],
+  );
+
+  const commitNewAssetFolder = useCallback(async () => {
+    const label = newFolderName.trim();
+    if (!label) {
+      setCreatingFolder(false);
+      setNewFolderName('');
+      return;
+    }
+    const folderId = `folder-${Date.now()}`;
+    setAssetFolders((currentFolders) => [
+      ...currentFolders,
+      createLocalAssetFolder({ folderId, label }),
+    ]);
+    setActiveUploadFolderId(folderId);
+    setCreatingFolder(false);
+    setNewFolderName('');
+    try {
+      const folder = await createEditorAssetFolder(
+        label,
+        assetFolders.length + 100,
+      );
+      setAssetFolders((currentFolders) =>
+        replaceLocalAssetFolder({
+          folders: currentFolders,
+          assets: [],
+          localFolderId: folderId,
+          persistedFolder: folder,
+        }).folders,
+      );
+      setAssets((currentAssets) =>
+        replaceLocalAssetFolder({
+          folders: [],
+          assets: currentAssets,
+          localFolderId: folderId,
+          persistedFolder: folder,
+        }).assets,
+      );
+      setActiveUploadFolderId(folder.folderId);
+    } catch {
+      // 本地临时文件夹仍可继续使用；下次刷新以后端为准。
+    }
+  }, [assetFolders.length, newFolderName]);
+
+  const deleteUploadedAsset = useCallback(
+    (asset: EditorAsset) => {
+      if (asset.sourceKind !== 'uploaded') {
+        return;
+      }
+      setAssets((currentAssets) => removeAssetById(currentAssets, asset.id));
+      onDeleteAssets?.([asset]);
+      setRenamingAsset((currentRename) =>
+        currentRename?.assetId === asset.id ? null : currentRename,
+      );
+      if (asset.persisted) {
+        deleteEditorAsset(asset.id).catch(() => {});
+      }
+    },
+    [onDeleteAssets],
+  );
+
+  const startRenamingFolder = useCallback((folder: EditorAssetFolder) => {
+    setRenamingFolder({
+      folderId: folder.id,
+      value: folder.label,
+    });
+  }, []);
+
+  const commitFolderRename = useCallback(
+    (folder: EditorAssetFolder) => {
+      const nextLabel = renamingFolder?.value.trim();
+      if (!nextLabel) {
+        setRenamingFolder(null);
+        return;
+      }
+      setAssetFolders((currentFolders) =>
+        renameAssetFolderById(currentFolders, folder.id, nextLabel),
+      );
+      if (folder.persisted) {
+        updateEditorAssetFolder(folder.id, { label: nextLabel }).catch(
+          () => {},
+        );
+      }
+      setRenamingFolder(null);
+    },
+    [renamingFolder],
+  );
+
+  const deleteAssetFolder = useCallback(
+    (folder: EditorAssetFolder) => {
+      if (folder.systemDefault) {
+        return;
+      }
+      const defaultFolder = resolveDefaultAssetFolder(assetFolders);
+      if (!defaultFolder) {
+        return;
+      }
+      setAssetFolders((currentFolders) =>
+        deleteAssetFolderLocally({
+          folders: currentFolders,
+          assets: [],
+          folderId: folder.id,
+          defaultFolderId: defaultFolder.id,
+        }).folders,
+      );
+      setAssets((currentAssets) =>
+        deleteAssetFolderLocally({
+          folders: [],
+          assets: currentAssets,
+          folderId: folder.id,
+          defaultFolderId: defaultFolder.id,
+        }).assets,
+      );
+      if (folder.persisted) {
+        deleteEditorAssetFolder(folder.id)
+          .then((library) => {
+            const nextLibrary = normalizeAssetLibrary(library);
+            setAssetFolders(nextLibrary.folders);
+            setAssets(nextLibrary.assets);
+          })
+          .catch(() => {});
+      }
+    },
+    [assetFolders],
+  );
+
+  const toggleAssetSelected = useCallback((assetId: string) => {
+    setSelectedAssetIds((currentIds) =>
+      toggleAssetSelection(currentIds, assetId),
+    );
+  }, []);
+
+  const toggleAllAssetsSelected = useCallback(() => {
+    setSelectedAssetIds(
+      resolveAllAssetSelection({
+        allSelectableAssetsSelected,
+        selectableAssets,
+      }),
+    );
+  }, [allSelectableAssetsSelected, selectableAssets]);
+
+  const deleteSelectedAssets = useCallback(() => {
+    const ids = [...selectedAssetIds];
+    const deletedAssets = removeSelectedAssets(assets, selectedAssetIds)
+      .deletedAssets;
+    setAssets(
+      (currentAssets) => removeSelectedAssets(currentAssets, selectedAssetIds).assets,
+    );
+    onDeleteAssets?.(deletedAssets);
+    setSelectedAssetIds(new Set());
+    ids.forEach((assetId) => {
+      void deleteEditorAsset(assetId);
+    });
+  }, [assets, onDeleteAssets, selectedAssetIds]);
+
+  const moveAssetToFolder = useCallback(
+    (assetId: string, folderId: string) => {
+      const asset = assets.find((currentAsset) => currentAsset.id === assetId);
+      if (!asset || asset.folderId === folderId) {
+        return;
+      }
+      setAssets((currentAssets) =>
+        moveAssetToFolderLocally(currentAssets, assetId, folderId),
+      );
+      if (asset.persisted) {
+        updateEditorAsset(asset.id, { folderId }).catch(() => {});
+      }
+    },
+    [assets],
+  );
+
+  const closeAssetSelectionMode = useCallback(() => {
+    setIsAssetSelectionMode(false);
+    setSelectedAssetIds(new Set());
+    setAssetMarquee(null);
+  }, []);
+
+  const updateAssetSelectionFromMarquee = useCallback(
+    (selectionRect: {
+      left: number;
+      right: number;
+      top: number;
+      bottom: number;
+    }) => {
+      setSelectedAssetIds(
+        selectUploadedAssetsInRect({
+          assets,
+          assetTargets: readAssetHitTargets(assetListRef.current),
+          selectionRect,
+        }),
+      );
+    },
+    [assetListRef, assets],
+  );
+
+  const handleAssetMarqueePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const target = event.target as HTMLElement;
+      if (
+        !shouldStartAssetMarquee({
+          isAssetSelectionMode,
+          button: event.button,
+          isBlockedTarget: Boolean(
+            target.closest(ASSET_MARQUEE_BLOCKED_TARGET_SELECTOR),
+          ),
+        })
+      ) {
+        return;
+      }
+      event.preventDefault();
+      assetListRef.current?.setPointerCapture?.(event.pointerId);
+      setAssetMarquee(
+        createAssetMarqueeFromPointer({
+          pointerId: event.pointerId,
+          point: event,
+          containerRect: assetListRef.current?.getBoundingClientRect(),
+        }),
+      );
+      setSelectedAssetIds(new Set());
+    },
+    [assetListRef, isAssetSelectionMode],
+  );
+
+  const handleAssetMarqueePointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (!assetMarquee || assetMarquee.pointerId !== event.pointerId) {
+        return;
+      }
+      event.preventDefault();
+      const containerRect = assetListRef.current?.getBoundingClientRect();
+      setAssetMarquee((currentMarquee) =>
+        currentMarquee
+          ? moveAssetMarqueeToPointer({
+              marquee: currentMarquee,
+              point: event,
+              containerRect,
+            })
+          : null,
+      );
+      updateAssetSelectionFromMarquee(
+        createAssetMarqueeSelectionRect({
+          marquee: assetMarquee,
+          point: event,
+          containerRect,
+        }),
+      );
+    },
+    [assetListRef, assetMarquee, updateAssetSelectionFromMarquee],
+  );
+
+  const handleAssetMarqueePointerUp = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (!assetMarquee || assetMarquee.pointerId !== event.pointerId) {
+        return;
+      }
+      event.preventDefault();
+      if (assetListRef.current?.hasPointerCapture?.(event.pointerId)) {
+        assetListRef.current.releasePointerCapture?.(event.pointerId);
+      }
+      setAssetMarquee(null);
+    },
+    [assetListRef, assetMarquee],
+  );
+
+  return {
+    assetFolders,
+    setAssetFolders,
+    assets,
+    setAssets,
+    groupedAssets,
+    selectableAssets,
+    allSelectableAssetsSelected,
+    renamingAsset,
+    setRenamingAsset,
+    renamingFolder,
+    setRenamingFolder,
+    creatingFolder,
+    setCreatingFolder,
+    newFolderName,
+    setNewFolderName,
+    activeUploadFolderId,
+    setActiveUploadFolderId,
+    isAssetSelectionMode,
+    setIsAssetSelectionMode,
+    selectedAssetIds,
+    setSelectedAssetIds,
+    assetMarquee,
+    setAssetMarquee,
+    assetPointerDrag,
+    setAssetPointerDrag,
+    assetMoveDropFolderId,
+    pinnedAssetMoveFolderId,
+    resolveAssetFolderId,
+    updateAssetMoveDropFolder,
+    startRenamingAsset,
+    commitAssetRename,
+    toggleAssetFolder,
+    commitNewAssetFolder,
+    deleteUploadedAsset,
+    startRenamingFolder,
+    commitFolderRename,
+    deleteAssetFolder,
+    toggleAssetSelected,
+    toggleAllAssetsSelected,
+    deleteSelectedAssets,
+    moveAssetToFolder,
+    closeAssetSelectionMode,
+    handleAssetMarqueePointerDown,
+    handleAssetMarqueePointerMove,
+    handleAssetMarqueePointerUp,
+  };
+}
+
+export type ImageCanvasAssetLibraryState = ReturnType<
+  typeof useImageCanvasAssetLibrary
+>;
+
+export type ImageCanvasAssetLibrarySetter<T> = Dispatch<SetStateAction<T>>;
diff --git a/src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx b/src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx
new file mode 100644
index 000000000..ab8d60074
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx
@@ -0,0 +1,263 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
+
+const defaultAssets: EditorAsset[] = [
+  {
+    id: 'asset-1',
+    label: '素材一',
+    src: 'data:image/png;base64,asset-1',
+    width: 320,
+    height: 240,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+  },
+];
+
+function dispatchPointerEvent(
+  type: string,
+  init: MouseEventInit & { pointerId: number },
+) {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  Object.defineProperty(event, 'pointerId', { value: init.pointerId });
+  window.dispatchEvent(event);
+}
+
+function AssetPointerDragBridgeHarness({
+  initialDrag,
+  assets = defaultAssets,
+  resolveAssetFolderId = vi.fn(() => null),
+  resolveCanvasPoint = vi.fn(() => null),
+  moveAssetToFolder = vi.fn(),
+  addAssetLayer = vi.fn(),
+}: {
+  initialDrag?: AssetPointerDragState | null;
+  assets?: EditorAsset[];
+  resolveAssetFolderId?: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint?: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number } | null;
+  moveAssetToFolder?: (assetId: string, folderId: string) => void;
+  addAssetLayer?: (asset: EditorAsset, position?: { x: number; y: number }) => void;
+}) {
+  const assetPointerDragRef = useRef<AssetPointerDragState | null>(
+    initialDrag ?? {
+      assetId: 'asset-1',
+      pointerId: 7,
+      startClientX: 10,
+      startClientY: 10,
+      currentClientX: 10,
+      currentClientY: 10,
+      active: false,
+      dropFolderId: null,
+    },
+  );
+  const suppressAssetClickRef = useRef(false);
+  const [assetPointerDrag, setAssetPointerDrag] =
+    useState<AssetPointerDragState | null>(assetPointerDragRef.current);
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+  const [dropFolderId, updateAssetMoveDropFolder] = useState<string | null>(
+    null,
+  );
+
+  useImageCanvasAssetPointerDragBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  return (
+    <div>
+      <span data-testid="drag-active">
+        {assetPointerDrag ? String(assetPointerDrag.active) : 'none'}
+      </span>
+      <span data-testid="drag-x">
+        {assetPointerDrag ? assetPointerDrag.currentClientX : 'none'}
+      </span>
+      <span data-testid="drop-target">{uploadDropTarget ?? '-'}</span>
+      <span data-testid="drop-folder">{dropFolderId ?? '-'}</span>
+      <span data-testid="suppressed">{String(suppressAssetClickRef.current)}</span>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetPointerDragBridge', () => {
+  it('activates sidebar asset drags and updates canvas and folder drop hints', () => {
+    const resolveAssetFolderId = vi.fn(() => 'folder-1');
+    const resolveCanvasPoint = vi.fn(() => ({ x: 100, y: 80 }));
+    render(
+      <AssetPointerDragBridgeHarness
+        resolveAssetFolderId={resolveAssetFolderId}
+        resolveCanvasPoint={resolveCanvasPoint}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointermove', {
+        pointerId: 7,
+        clientX: 18,
+        clientY: 18,
+      });
+    });
+
+    expect(screen.getByTestId('drag-active').textContent).toBe('true');
+    expect(screen.getByTestId('drag-x').textContent).toBe('18');
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+    expect(screen.getByTestId('drop-folder').textContent).toBe('folder-1');
+  });
+
+  it('moves an active asset drag into a different folder on pointer up', () => {
+    const moveAssetToFolder = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 30,
+          currentClientY: 30,
+          active: true,
+          dropFolderId: 'folder-1',
+        }}
+        resolveAssetFolderId={() => 'folder-1'}
+        moveAssetToFolder={moveAssetToFolder}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 30,
+        clientY: 30,
+      });
+    });
+
+    expect(moveAssetToFolder).toHaveBeenCalledWith('asset-1', 'folder-1');
+    expect(screen.getByTestId('drag-active').textContent).toBe('none');
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+    expect(screen.getByTestId('drop-folder').textContent).toBe('-');
+    expect(screen.getByTestId('suppressed').textContent).toBe('true');
+  });
+
+  it('adds an active dragged asset to the canvas when released over the canvas', () => {
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 48,
+          currentClientY: 64,
+          active: true,
+          dropFolderId: null,
+        }}
+        resolveCanvasPoint={() => ({ x: 480, y: 640 })}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 48,
+        clientY: 64,
+      });
+    });
+
+    expect(addAssetLayer).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'asset-1' }),
+      { x: 480, y: 640 },
+    );
+  });
+
+  it('cleans up inactive drags without moving or adding assets', () => {
+    const moveAssetToFolder = vi.fn();
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 10,
+          currentClientY: 10,
+          active: false,
+          dropFolderId: 'folder-1',
+        }}
+        moveAssetToFolder={moveAssetToFolder}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 10,
+        clientY: 10,
+      });
+    });
+
+    expect(moveAssetToFolder).not.toHaveBeenCalled();
+    expect(addAssetLayer).not.toHaveBeenCalled();
+    expect(screen.getByTestId('drag-active').textContent).toBe('none');
+  });
+
+  it('uses the same finish path for pointer cancellation', () => {
+    const moveAssetToFolder = vi.fn();
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 8,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 24,
+          currentClientY: 24,
+          active: true,
+          dropFolderId: 'folder-1',
+        }}
+        moveAssetToFolder={moveAssetToFolder}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointercancel', {
+        pointerId: 8,
+        clientX: 24,
+        clientY: 24,
+      });
+    });
+
+    expect(moveAssetToFolder).toHaveBeenCalledWith('asset-1', 'folder-1');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasAssetPointerDragBridge.ts b/src/components/image-editor/useImageCanvasAssetPointerDragBridge.ts
new file mode 100644
index 000000000..f6695b58e
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasAssetPointerDragBridge.ts
@@ -0,0 +1,140 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+
+type CanvasPoint = { x: number; y: number };
+
+type UseImageCanvasAssetPointerDragBridgeOptions = {
+  assetPointerDragRef: RefObject<AssetPointerDragState | null>;
+  suppressAssetClickRef: RefObject<boolean>;
+  assets: EditorAsset[];
+  resolveAssetFolderId: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint: (clientX: number, clientY: number) => CanvasPoint | null;
+  setAssetPointerDrag: (dragState: AssetPointerDragState | null) => void;
+  setUploadDropTarget: (target: 'canvas' | 'assets' | null) => void;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  addAssetLayer: (asset: EditorAsset, position?: CanvasPoint) => void;
+};
+
+export function useImageCanvasAssetPointerDragBridge({
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  assets,
+  resolveAssetFolderId,
+  resolveCanvasPoint,
+  setAssetPointerDrag,
+  setUploadDropTarget,
+  updateAssetMoveDropFolder,
+  moveAssetToFolder,
+  addAssetLayer,
+}: UseImageCanvasAssetPointerDragBridgeOptions) {
+  const assetsRef = useRef(assets);
+  const callbacksRef = useRef({
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  useEffect(() => {
+    assetsRef.current = assets;
+  }, [assets]);
+
+  callbacksRef.current = {
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  };
+
+  useEffect(() => {
+    const updatePointerDrag = (event: PointerEvent) => {
+      const currentDrag = assetPointerDragRef.current;
+      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
+        return;
+      }
+      const {
+        resolveAssetFolderId: resolveFolder,
+        resolveCanvasPoint: resolvePoint,
+        setAssetPointerDrag: setPointerDrag,
+        setUploadDropTarget: setDropTarget,
+        updateAssetMoveDropFolder: updateDropFolder,
+      } = callbacksRef.current;
+      const distance = Math.hypot(
+        event.clientX - currentDrag.startClientX,
+        event.clientY - currentDrag.startClientY,
+      );
+      const dropFolderId = resolveFolder(event.clientX, event.clientY);
+      const nextDrag: AssetPointerDragState = {
+        ...currentDrag,
+        currentClientX: event.clientX,
+        currentClientY: event.clientY,
+        active: currentDrag.active || distance > 4,
+        dropFolderId,
+      };
+      assetPointerDragRef.current = nextDrag;
+      setPointerDrag(nextDrag);
+      setDropTarget(resolvePoint(event.clientX, event.clientY) ? 'canvas' : null);
+      updateDropFolder(dropFolderId);
+    };
+
+    const finishPointerDrag = (event: PointerEvent) => {
+      const currentDrag = assetPointerDragRef.current;
+      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
+        return;
+      }
+      const {
+        resolveAssetFolderId: resolveFolder,
+        resolveCanvasPoint: resolvePoint,
+        setAssetPointerDrag: setPointerDrag,
+        setUploadDropTarget: setDropTarget,
+        updateAssetMoveDropFolder: updateDropFolder,
+        moveAssetToFolder: moveToFolder,
+        addAssetLayer: addLayer,
+      } = callbacksRef.current;
+      const canvasPoint = resolvePoint(event.clientX, event.clientY);
+      const dropFolderId =
+        resolveFolder(event.clientX, event.clientY) ?? currentDrag.dropFolderId;
+      const draggedAsset = assetsRef.current.find(
+        (asset) => asset.id === currentDrag.assetId,
+      );
+      assetPointerDragRef.current = null;
+      setPointerDrag(null);
+      setDropTarget(null);
+      updateDropFolder(null);
+      if (!currentDrag.active || !draggedAsset) {
+        return;
+      }
+      suppressAssetClickRef.current = true;
+      window.setTimeout(() => {
+        suppressAssetClickRef.current = false;
+      }, 0);
+      if (dropFolderId && dropFolderId !== draggedAsset.folderId) {
+        moveToFolder(draggedAsset.id, dropFolderId);
+        return;
+      }
+      if (canvasPoint) {
+        addLayer(draggedAsset, canvasPoint);
+      }
+    };
+
+    window.addEventListener('pointermove', updatePointerDrag);
+    window.addEventListener('pointerup', finishPointerDrag);
+    window.addEventListener('pointercancel', finishPointerDrag);
+    return () => {
+      window.removeEventListener('pointermove', updatePointerDrag);
+      window.removeEventListener('pointerup', finishPointerDrag);
+      window.removeEventListener('pointercancel', finishPointerDrag);
+    };
+  }, [assetPointerDragRef, suppressAssetClickRef]);
+}
diff --git a/src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx
new file mode 100644
index 000000000..b09eee050
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.test.tsx
@@ -0,0 +1,244 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ASSET_DRAG_MIME_TYPE } from './ImageCanvasEditorModel';
+import type { EditorAsset, EditorAssetFolder } from './ImageCanvasEditorTypes';
+import { useImageCanvasCanvasDropWorkflow } from './useImageCanvasCanvasDropWorkflow';
+
+function createDataTransferStub({
+  files = [],
+}: {
+  files?: File[];
+} = {}) {
+  const store = new Map<string, string>();
+  return {
+    files,
+    types: files.length ? ['Files'] : ([] as string[]),
+    dropEffect: 'none',
+    setData(type: string, value: string) {
+      store.set(type, value);
+      if (!this.types.includes(type)) {
+        this.types.push(type);
+      }
+    },
+    getData(type: string) {
+      return store.get(type) ?? '';
+    },
+  };
+}
+
+function dispatchDragEvent(
+  target: Element,
+  type: string,
+  options: {
+    dataTransfer: ReturnType<typeof createDataTransferStub>;
+    clientX?: number;
+    clientY?: number;
+    relatedTarget?: EventTarget | null;
+  },
+) {
+  const event = new Event(type, { bubbles: true, cancelable: true });
+  Object.defineProperty(event, 'dataTransfer', {
+    configurable: true,
+    value: options.dataTransfer,
+  });
+  Object.defineProperty(event, 'clientX', {
+    configurable: true,
+    value: options.clientX ?? 0,
+  });
+  Object.defineProperty(event, 'clientY', {
+    configurable: true,
+    value: options.clientY ?? 0,
+  });
+  Object.defineProperty(event, 'relatedTarget', {
+    configurable: true,
+    value: options.relatedTarget ?? null,
+  });
+  fireEvent(target, event);
+}
+
+function DropWorkflowHarness({
+  assets = [
+    {
+      id: 'asset-1',
+      label: '素材一',
+      src: 'data:image/png;base64,asset',
+      width: 100,
+      height: 80,
+      folderId: 'project',
+      sourceKind: 'uploaded',
+      sourceType: 'uploaded',
+      persisted: true,
+    },
+  ],
+  folders = [
+    {
+      id: 'project',
+      label: '项目素材',
+      collapsed: false,
+      systemDefault: true,
+      persisted: true,
+    },
+  ],
+  addAssetLayer = vi.fn(),
+  addUploadedFiles = vi.fn(),
+  updateAssetMoveDropFolder = vi.fn(),
+  getCanvasDropPoint = vi.fn((clientX: number, clientY: number) => ({
+    x: clientX - 10,
+    y: clientY - 20,
+  })),
+}: {
+  assets?: EditorAsset[];
+  folders?: EditorAssetFolder[];
+  addAssetLayer?: (asset: EditorAsset, position?: { x: number; y: number }) => void;
+  addUploadedFiles?: (
+    files: FileList | File[],
+    options: {
+      folderId?: string;
+      canvasPoint: { x: number; y: number };
+      addToCanvas: true;
+    },
+  ) => void;
+  updateAssetMoveDropFolder?: (folderId: string | null) => void;
+  getCanvasDropPoint?: (clientX: number, clientY: number) => {
+    x: number;
+    y: number;
+  };
+}) {
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+  const workflow = useImageCanvasCanvasDropWorkflow({
+    assets,
+    assetFolders: folders,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    getCanvasDropPoint,
+    addAssetLayer,
+    addUploadedFiles,
+  });
+
+  return (
+    <div>
+      <div
+        data-testid="outside"
+        onDragEnter={() => setUploadDropTarget('assets')}
+      />
+      <div
+        data-testid="canvas"
+        onDragOver={workflow.handleCanvasDragOver}
+        onDragLeave={workflow.handleCanvasDragLeave}
+        onDrop={workflow.handleCanvasDrop}
+      >
+        canvas
+        <span data-testid="drop-target">{uploadDropTarget ?? '-'}</span>
+        <span data-testid="inner">inner</span>
+      </div>
+    </div>
+  );
+}
+
+describe('useImageCanvasCanvasDropWorkflow', () => {
+  it('shows a canvas drop target for dragged asset library images', () => {
+    render(<DropWorkflowHarness />);
+    const dataTransfer = createDataTransferStub();
+    dataTransfer.setData(ASSET_DRAG_MIME_TYPE, 'asset-1');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragover', {
+      dataTransfer,
+    });
+
+    expect(dataTransfer.dropEffect).toBe('copy');
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+  });
+
+  it('adds an existing asset to the canvas at the drop point', () => {
+    const addAssetLayer = vi.fn();
+    const updateAssetMoveDropFolder = vi.fn();
+    render(
+      <DropWorkflowHarness
+        addAssetLayer={addAssetLayer}
+        updateAssetMoveDropFolder={updateAssetMoveDropFolder}
+      />,
+    );
+    const dataTransfer = createDataTransferStub();
+    dataTransfer.setData(ASSET_DRAG_MIME_TYPE, 'asset-1');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'drop', {
+      clientX: 120,
+      clientY: 90,
+      dataTransfer,
+    });
+
+    expect(addAssetLayer).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'asset-1' }),
+      { x: 110, y: 70 },
+    );
+    expect(updateAssetMoveDropFolder).toHaveBeenCalledWith(null);
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+  });
+
+  it('uploads dropped files to the default folder and adds them to the canvas', () => {
+    const addUploadedFiles = vi.fn();
+    render(<DropWorkflowHarness addUploadedFiles={addUploadedFiles} />);
+    const imageFile = new File(['image'], '画布上传.png', {
+      type: 'image/png',
+    });
+    const dataTransfer = createDataTransferStub({ files: [imageFile] });
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragover', {
+      dataTransfer,
+    });
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'drop', {
+      clientX: 300,
+      clientY: 220,
+      dataTransfer,
+    });
+
+    expect(addUploadedFiles).toHaveBeenCalledWith([imageFile], {
+      folderId: 'project',
+      canvasPoint: { x: 290, y: 200 },
+      addToCanvas: true,
+    });
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+  });
+
+  it('keeps unrelated drags untouched and clears only canvas overlays on leave', () => {
+    render(<DropWorkflowHarness />);
+    const dataTransfer = createDataTransferStub();
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragover', {
+      dataTransfer,
+    });
+
+    expect(dataTransfer.dropEffect).toBe('none');
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+
+    fireEvent.dragEnter(screen.getByTestId('outside'));
+    expect(screen.getByTestId('drop-target').textContent).toBe('assets');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragover', {
+      dataTransfer: createDataTransferStub({
+        files: [new File(['image'], '画布上传.png', { type: 'image/png' })],
+      }),
+    });
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragleave', {
+      dataTransfer: createDataTransferStub(),
+      relatedTarget: screen.getByTestId('inner'),
+    });
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+
+    dispatchDragEvent(screen.getByTestId('canvas'), 'dragleave', {
+      dataTransfer: createDataTransferStub(),
+      relatedTarget: screen.getByTestId('outside'),
+    });
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts
new file mode 100644
index 000000000..48f961876
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasCanvasDropWorkflow.ts
@@ -0,0 +1,131 @@
+import {
+  type DragEvent as ReactDragEvent,
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+} from 'react';
+
+import {
+  ASSET_DRAG_MIME_TYPE,
+  getDraggedAssetId,
+  hasDataTransferType,
+} from './ImageCanvasEditorModel';
+import type { EditorAsset, EditorAssetFolder } from './ImageCanvasEditorTypes';
+
+type UploadFilesToCanvasOptions = {
+  folderId?: string;
+  canvasPoint: { x: number; y: number };
+  addToCanvas: true;
+};
+
+type UseImageCanvasCanvasDropWorkflowOptions = {
+  assets: EditorAsset[];
+  assetFolders: EditorAssetFolder[];
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  getCanvasDropPoint: (clientX: number, clientY: number) => {
+    x: number;
+    y: number;
+  };
+  addAssetLayer: (
+    asset: EditorAsset,
+    position?: { x: number; y: number },
+  ) => void;
+  addUploadedFiles: (
+    files: FileList | File[],
+    options: UploadFilesToCanvasOptions,
+  ) => void;
+};
+
+export function useImageCanvasCanvasDropWorkflow({
+  assets,
+  assetFolders,
+  setUploadDropTarget,
+  updateAssetMoveDropFolder,
+  getCanvasDropPoint,
+  addAssetLayer,
+  addUploadedFiles,
+}: UseImageCanvasCanvasDropWorkflowOptions) {
+  const handleCanvasDragOver = useCallback(
+    (event: ReactDragEvent<HTMLDivElement>) => {
+      if (hasDataTransferType(event.dataTransfer, ASSET_DRAG_MIME_TYPE)) {
+        event.preventDefault();
+        setUploadDropTarget('canvas');
+        event.dataTransfer.dropEffect = 'copy';
+        return;
+      }
+      if (hasDataTransferType(event.dataTransfer, 'Files')) {
+        event.preventDefault();
+        setUploadDropTarget('canvas');
+        event.dataTransfer.dropEffect = 'copy';
+      }
+    },
+    [setUploadDropTarget],
+  );
+
+  const handleCanvasDragLeave = useCallback(
+    (event: ReactDragEvent<HTMLDivElement>) => {
+      if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+        setUploadDropTarget((currentTarget) =>
+          currentTarget === 'canvas' ? null : currentTarget,
+        );
+      }
+    },
+    [setUploadDropTarget],
+  );
+
+  const handleCanvasDrop = useCallback(
+    (event: ReactDragEvent<HTMLDivElement>) => {
+      const draggedAssetId = getDraggedAssetId(event.dataTransfer);
+      if (draggedAssetId) {
+        const draggedAsset = assets.find((asset) => asset.id === draggedAssetId);
+        if (!draggedAsset) {
+          return;
+        }
+        event.preventDefault();
+        setUploadDropTarget(null);
+        updateAssetMoveDropFolder(null);
+        addAssetLayer(
+          draggedAsset,
+          getCanvasDropPoint(event.clientX, event.clientY),
+        );
+        return;
+      }
+
+      const files = event.dataTransfer.files;
+      if (!files.length) {
+        return;
+      }
+      event.preventDefault();
+      setUploadDropTarget(null);
+      updateAssetMoveDropFolder(null);
+      const canvasPoint = getCanvasDropPoint(event.clientX, event.clientY);
+      const defaultFolder =
+        assetFolders.find((folder) => folder.systemDefault) ?? assetFolders[0];
+      addUploadedFiles(files, {
+        folderId: defaultFolder?.id,
+        canvasPoint,
+        addToCanvas: true,
+      });
+    },
+    [
+      addAssetLayer,
+      addUploadedFiles,
+      assetFolders,
+      assets,
+      getCanvasDropPoint,
+      setUploadDropTarget,
+      updateAssetMoveDropFolder,
+    ],
+  );
+
+  return useMemo(
+    () => ({
+      handleCanvasDragOver,
+      handleCanvasDragLeave,
+      handleCanvasDrop,
+    }),
+    [handleCanvasDragLeave, handleCanvasDragOver, handleCanvasDrop],
+  );
+}
diff --git a/src/components/image-editor/useImageCanvasEditorChrome.test.tsx b/src/components/image-editor/useImageCanvasEditorChrome.test.tsx
new file mode 100644
index 000000000..03f8da9fb
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasEditorChrome.test.tsx
@@ -0,0 +1,224 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
+
+const renameEditorProjectMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    renameEditorProject: renameEditorProjectMock,
+  };
+});
+
+function ChromeHarness({
+  openEditorLoginModal = vi.fn(),
+}: {
+  openEditorLoginModal?: (postLoginAction?: (() => void) | null) => void;
+}) {
+  const chrome = useImageCanvasEditorChrome({ openEditorLoginModal });
+
+  return (
+    <div>
+      <span data-testid="title">{chrome.projectTitle}</span>
+      <span data-testid="rename-value">{chrome.projectRenameValue}</span>
+      <span data-testid="renaming">{String(chrome.isRenamingProject)}</span>
+      <span data-testid="saving">{String(chrome.isProjectRenameSaving)}</span>
+      <span data-testid="rename-error">{chrome.projectRenameError ?? '-'}</span>
+      <span data-testid="sidebar">{chrome.activeSidebarPanel ?? '-'}</span>
+      <span data-testid="tool">{chrome.activeTool}</span>
+      <span data-testid="zoom">{String(chrome.isZoomMenuOpen)}</span>
+      <span data-testid="background-open">
+        {String(chrome.isBackgroundSettingsOpen)}
+      </span>
+      <span data-testid="minimap">{String(chrome.isMinimapOpen)}</span>
+      <span data-testid="background-color">
+        {chrome.canvasBackgroundColor}
+      </span>
+      <span data-testid="background-hex">
+        {chrome.canvasBackgroundHexValue}
+      </span>
+      <button type="button" onClick={chrome.startProjectRename}>
+        start rename
+      </button>
+      <button type="button" onClick={chrome.cancelProjectRename}>
+        cancel rename
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.submitProjectRename('project-1')}
+      >
+        submit rename
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.submitProjectRename(null)}
+      >
+        submit without project
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.setProjectRenameValue('  新项目  ')}
+      >
+        set rename
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.setProjectRenameValue('   ')}
+      >
+        blank rename
+      </button>
+      <button type="button" onClick={() => chrome.setProjectTitle('已有项目')}>
+        set title
+      </button>
+      <button type="button" onClick={() => chrome.setActiveTool('hand')}>
+        set hand
+      </button>
+      <button type="button" onClick={() => chrome.toggleSidebarPanel('assets')}>
+        toggle assets
+      </button>
+      <button type="button" onClick={() => chrome.toggleSidebarPanel('layers')}>
+        toggle layers
+      </button>
+      <button type="button" onClick={chrome.toggleZoomMenu}>
+        toggle zoom
+      </button>
+      <button type="button" onClick={chrome.toggleBackgroundSettings}>
+        toggle background
+      </button>
+      <button type="button" onClick={chrome.toggleMinimap}>
+        toggle minimap
+      </button>
+      <button type="button" onClick={chrome.closeEditorChromePanels}>
+        close panels
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.applyCanvasBackgroundColor('#abc')}
+      >
+        apply short hex
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.handleCanvasBackgroundHexChange('#not-a-color')}
+      >
+        invalid hex
+      </button>
+      <button
+        type="button"
+        onClick={() => chrome.handleCanvasBackgroundHexChange('#ffffff')}
+      >
+        valid hex
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasEditorChrome', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renames projects and resets rename state from the saved title', async () => {
+    renameEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'project-1',
+      title: '后端项目名',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-17T00:00:00.000Z',
+    });
+    render(<ChromeHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'set title' }));
+    fireEvent.click(screen.getByRole('button', { name: 'start rename' }));
+    expect(screen.getByTestId('rename-value').textContent).toBe('已有项目');
+
+    fireEvent.click(screen.getByRole('button', { name: 'set rename' }));
+    fireEvent.click(screen.getByRole('button', { name: 'submit rename' }));
+    expect(screen.getByTestId('saving').textContent).toBe('true');
+
+    await waitFor(() => {
+      expect(renameEditorProjectMock).toHaveBeenCalledWith(
+        'project-1',
+        '新项目',
+      );
+    });
+    expect(screen.getByTestId('title').textContent).toBe('后端项目名');
+    expect(screen.getByTestId('rename-value').textContent).toBe('后端项目名');
+    expect(screen.getByTestId('renaming').textContent).toBe('false');
+    expect(screen.getByTestId('saving').textContent).toBe('false');
+  });
+
+  it('validates rename input and opens login on rename auth errors', async () => {
+    const openEditorLoginModal = vi.fn();
+    renameEditorProjectMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+    render(<ChromeHarness openEditorLoginModal={openEditorLoginModal} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'blank rename' }));
+    fireEvent.click(screen.getByRole('button', { name: 'submit rename' }));
+    expect(screen.getByTestId('rename-error').textContent).toBe(
+      '项目名称不能为空',
+    );
+    expect(renameEditorProjectMock).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByRole('button', { name: 'set rename' }));
+    fireEvent.click(screen.getByRole('button', { name: 'submit rename' }));
+
+    await waitFor(() => {
+      expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+    });
+    expect(screen.getByTestId('rename-error').textContent).toBe('未授权访问');
+  });
+
+  it('manages background colors and chrome panel toggles', () => {
+    render(<ChromeHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'apply short hex' }));
+    expect(screen.getByTestId('background-color').textContent).toBe('#aabbcc');
+    expect(screen.getByTestId('background-hex').textContent).toBe('#aabbcc');
+
+    fireEvent.click(screen.getByRole('button', { name: 'invalid hex' }));
+    expect(screen.getByTestId('background-color').textContent).toBe('#aabbcc');
+    expect(screen.getByTestId('background-hex').textContent).toBe(
+      '#not-a-color',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'valid hex' }));
+    expect(screen.getByTestId('background-color').textContent).toBe('#ffffff');
+    expect(screen.getByTestId('background-hex').textContent).toBe('#ffffff');
+
+    fireEvent.click(screen.getByRole('button', { name: 'toggle assets' }));
+    expect(screen.getByTestId('sidebar').textContent).toBe('-');
+    fireEvent.click(screen.getByRole('button', { name: 'toggle layers' }));
+    expect(screen.getByTestId('sidebar').textContent).toBe('layers');
+    fireEvent.click(screen.getByRole('button', { name: 'toggle zoom' }));
+    fireEvent.click(screen.getByRole('button', { name: 'toggle background' }));
+    fireEvent.click(screen.getByRole('button', { name: 'toggle minimap' }));
+    fireEvent.click(screen.getByRole('button', { name: 'set hand' }));
+    expect(screen.getByTestId('zoom').textContent).toBe('true');
+    expect(screen.getByTestId('background-open').textContent).toBe('true');
+    expect(screen.getByTestId('minimap').textContent).toBe('false');
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+
+    act(() => {
+      screen.getByRole('button', { name: 'close panels' }).click();
+    });
+    expect(screen.getByTestId('sidebar').textContent).toBe('-');
+    expect(screen.getByTestId('zoom').textContent).toBe('false');
+    expect(screen.getByTestId('background-open').textContent).toBe('false');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasEditorChrome.ts b/src/components/image-editor/useImageCanvasEditorChrome.ts
new file mode 100644
index 000000000..87cc65f89
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasEditorChrome.ts
@@ -0,0 +1,177 @@
+import { useCallback, useState } from 'react';
+
+import { ApiClientError } from '../../services/apiClient';
+import { renameEditorProject } from '../../services/image-editor/editorProjectClient';
+import {
+  DEFAULT_CANVAS_BACKGROUND_COLOR,
+  normalizeCanvasBackgroundHex,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasTool,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+
+type UseImageCanvasEditorChromeOptions = {
+  openEditorLoginModal: (postLoginAction?: (() => void) | null) => void;
+};
+
+function isEditorAuthError(error: unknown) {
+  return (
+    error instanceof ApiClientError &&
+    (error.status === 401 || error.status === 403)
+  );
+}
+
+export function useImageCanvasEditorChrome({
+  openEditorLoginModal,
+}: UseImageCanvasEditorChromeOptions) {
+  const [projectTitle, setProjectTitle] = useState('未命名画布');
+  const [projectRenameValue, setProjectRenameValue] = useState('未命名画布');
+  const [isRenamingProject, setIsRenamingProject] = useState(false);
+  const [isProjectRenameSaving, setIsProjectRenameSaving] = useState(false);
+  const [projectRenameError, setProjectRenameError] = useState<string | null>(
+    null,
+  );
+  const [activeSidebarPanel, setActiveSidebarPanel] =
+    useState<SidebarPanel | null>('assets');
+  const [activeTool, setActiveTool] = useState<CanvasTool>('select');
+  const [isZoomMenuOpen, setIsZoomMenuOpen] = useState(false);
+  const [isBackgroundSettingsOpen, setIsBackgroundSettingsOpen] =
+    useState(false);
+  const [isMinimapOpen, setIsMinimapOpen] = useState(true);
+  const [canvasBackgroundColor, setCanvasBackgroundColor] = useState(
+    DEFAULT_CANVAS_BACKGROUND_COLOR,
+  );
+  const [canvasBackgroundHexValue, setCanvasBackgroundHexValue] = useState(
+    DEFAULT_CANVAS_BACKGROUND_COLOR,
+  );
+
+  const applyCanvasBackgroundColor = useCallback((color: string) => {
+    const normalizedColor = normalizeCanvasBackgroundHex(color);
+    if (!normalizedColor) {
+      return false;
+    }
+    setCanvasBackgroundColor(normalizedColor);
+    setCanvasBackgroundHexValue(normalizedColor);
+    return true;
+  }, []);
+
+  const handleCanvasBackgroundHexChange = useCallback((nextValue: string) => {
+    setCanvasBackgroundHexValue(nextValue);
+    const normalizedColor = normalizeCanvasBackgroundHex(nextValue);
+    if (normalizedColor) {
+      setCanvasBackgroundColor(normalizedColor);
+      setCanvasBackgroundHexValue(normalizedColor);
+    }
+  }, []);
+
+  const startProjectRename = useCallback(() => {
+    setProjectRenameValue(projectTitle);
+    setProjectRenameError(null);
+    setIsRenamingProject(true);
+  }, [projectTitle]);
+
+  const cancelProjectRename = useCallback(() => {
+    setProjectRenameValue(projectTitle);
+    setProjectRenameError(null);
+    setIsRenamingProject(false);
+  }, [projectTitle]);
+
+  const submitProjectRename = useCallback(
+    (projectId: string | null) => {
+      const nextTitle = projectRenameValue.trim();
+      if (!nextTitle) {
+        setProjectRenameError('项目名称不能为空');
+        return;
+      }
+      if (!projectId || nextTitle === projectTitle) {
+        setProjectRenameValue(projectTitle);
+        setProjectRenameError(null);
+        setIsRenamingProject(false);
+        return;
+      }
+      setIsProjectRenameSaving(true);
+      setProjectRenameError(null);
+      renameEditorProject(projectId, nextTitle)
+        .then((project: Awaited<ReturnType<typeof renameEditorProject>>) => {
+          const savedTitle = project.title?.trim() || nextTitle;
+          setProjectTitle(savedTitle);
+          setProjectRenameValue(savedTitle);
+          setIsRenamingProject(false);
+        })
+        .catch((error: unknown) => {
+          if (isEditorAuthError(error)) {
+            openEditorLoginModal();
+          }
+          setProjectRenameError(
+            error instanceof Error ? error.message : '重命名项目失败',
+          );
+        })
+        .finally(() => setIsProjectRenameSaving(false));
+    },
+    [openEditorLoginModal, projectRenameValue, projectTitle],
+  );
+
+  const resetProjectRenameError = useCallback(() => {
+    setProjectRenameError(null);
+  }, []);
+
+  const closeEditorChromePanels = useCallback(() => {
+    setActiveSidebarPanel(null);
+    setIsZoomMenuOpen(false);
+    setIsBackgroundSettingsOpen(false);
+  }, []);
+
+  const toggleSidebarPanel = useCallback((panel: SidebarPanel) => {
+    setActiveSidebarPanel((currentPanel) =>
+      currentPanel === panel ? null : panel,
+    );
+  }, []);
+
+  const toggleZoomMenu = useCallback(() => {
+    setIsZoomMenuOpen((open) => !open);
+  }, []);
+
+  const closeZoomMenu = useCallback(() => {
+    setIsZoomMenuOpen(false);
+  }, []);
+
+  const toggleBackgroundSettings = useCallback(() => {
+    setIsBackgroundSettingsOpen((isOpen) => !isOpen);
+  }, []);
+
+  const toggleMinimap = useCallback(() => {
+    setIsMinimapOpen((open) => !open);
+  }, []);
+
+  return {
+    projectTitle,
+    setProjectTitle,
+    projectRenameValue,
+    setProjectRenameValue,
+    isRenamingProject,
+    isProjectRenameSaving,
+    projectRenameError,
+    activeSidebarPanel,
+    setActiveSidebarPanel,
+    activeTool,
+    setActiveTool,
+    isZoomMenuOpen,
+    isBackgroundSettingsOpen,
+    isMinimapOpen,
+    canvasBackgroundColor,
+    canvasBackgroundHexValue,
+    startProjectRename,
+    cancelProjectRename,
+    submitProjectRename,
+    resetProjectRenameError,
+    applyCanvasBackgroundColor,
+    handleCanvasBackgroundHexChange,
+    closeEditorChromePanels,
+    toggleSidebarPanel,
+    toggleZoomMenu,
+    closeZoomMenu,
+    toggleBackgroundSettings,
+    toggleMinimap,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasFloatingOptionDismiss.ts b/src/components/image-editor/useImageCanvasFloatingOptionDismiss.ts
new file mode 100644
index 000000000..de8ba389c
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasFloatingOptionDismiss.ts
@@ -0,0 +1,60 @@
+import { useEffect } from 'react';
+
+type FloatingOptionBoundaryRef = {
+  readonly current: HTMLElement | null;
+};
+
+type UseImageCanvasFloatingOptionDismissOptions = {
+  isOpen: boolean;
+  boundaryRefs: Array<FloatingOptionBoundaryRef | null | undefined>;
+  onDismiss: () => void;
+};
+
+function isEventInsideBoundary(
+  target: EventTarget | null,
+  boundaryRefs: Array<FloatingOptionBoundaryRef | null | undefined>,
+) {
+  if (!(target instanceof Node)) {
+    return false;
+  }
+
+  return boundaryRefs.some((boundaryRef) => {
+    const element = boundaryRef?.current;
+    return element ? element.contains(target) : false;
+  });
+}
+
+function isEventInsideFloatingMenu(target: EventTarget | null) {
+  return (
+    target instanceof Element &&
+    target.closest('.image-canvas-editor__portal-menu')
+  );
+}
+
+export function useImageCanvasFloatingOptionDismiss({
+  isOpen,
+  boundaryRefs,
+  onDismiss,
+}: UseImageCanvasFloatingOptionDismissOptions) {
+  useEffect(() => {
+    if (!isOpen || typeof document === 'undefined') {
+      return undefined;
+    }
+
+    const handleClick = (event: MouseEvent) => {
+      // 中文注释：选项项点击后要保留浮层；父级面板其它区域点击才收起。
+      if (
+        isEventInsideBoundary(event.target, boundaryRefs) ||
+        isEventInsideFloatingMenu(event.target)
+      ) {
+        return;
+      }
+      onDismiss();
+    };
+
+    document.addEventListener('click', handleClick);
+    return () => {
+      document.removeEventListener('click', handleClick);
+    };
+  }, [boundaryRefs, isOpen, onDismiss]);
+}
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
new file mode 100644
index 000000000..e2be81057
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
@@ -0,0 +1,1303 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  CharacterAnimationPanelState,
+  GenerateDialogState,
+  QuickEditPanelState,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+import { createQuickEditPanelDraft } from './ImageCanvasGenerationDialogModel';
+import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
+import { useImageCanvasGenerationSubmissionWorkflow } from './useImageCanvasGenerationSubmissionWorkflow';
+
+const resolveEditorImageReferenceDataUrlMock = vi.hoisted(() => vi.fn());
+const resolveEditorImageReferenceDataUrlForGenerationMock = vi.hoisted(() =>
+  vi.fn(),
+);
+const editEditorImageMock = vi.hoisted(() => vi.fn());
+const extractEditorUiDesignAssetsMock = vi.hoisted(() => vi.fn());
+const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
+const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
+const generateEditorImageMock = vi.hoisted(() => vi.fn());
+const generateEditorVideoMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorImageReference', () => ({
+  resolveEditorImageReferenceDataUrl: resolveEditorImageReferenceDataUrlMock,
+  resolveEditorImageReferenceDataUrlForGeneration:
+    resolveEditorImageReferenceDataUrlForGenerationMock,
+}));
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: editEditorImageMock,
+    extractEditorUiDesignAssets: extractEditorUiDesignAssetsMock,
+    generateEditorCharacterAnimation: generateEditorCharacterAnimationMock,
+    generateEditorIconSpritesheet: generateEditorIconSpritesheetMock,
+    generateEditorImage: generateEditorImageMock,
+    generateEditorVideo: generateEditorVideoMock,
+  };
+});
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '源图',
+    src: 'https://assets.example.test/source.png',
+    x: 120,
+    y: 140,
+    width: 320,
+    height: 240,
+    originalWidth: 1024,
+    originalHeight: 768,
+    zIndex: 2,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createGenerated(overrides = {}) {
+  return {
+    imageSrc: 'data:image/png;base64,generated',
+    width: 1024,
+    height: 1024,
+    sourceType: 'generated' as const,
+    prompt: '生成提示词',
+    actualPrompt: '生成提示词',
+    model: 'gpt-image-2',
+    provider: 'VectorEngine',
+    taskId: 'task-generated',
+    ...overrides,
+  };
+}
+
+function createVideoGenerated(overrides = {}) {
+  return {
+    videoSrc: 'https://assets.example.test/generated-video.mp4',
+    width: 854,
+    height: 480,
+    sourceType: 'generated' as const,
+    prompt: '视频提示词',
+    actualPrompt: '视频提示词',
+    model: 'seedance2.0-fast',
+    provider: 'ark',
+    taskId: 'task-video-generated',
+    priceMudPoints: 40,
+    ...overrides,
+  };
+}
+
+function createIconResult(name: string, imageSrc: string) {
+  return {
+    name,
+    imageSrc,
+    width: 128,
+    height: 128,
+  };
+}
+
+function SubmissionWorkflowHarness({
+  initialDialog = null,
+  initialQuickEditPanel = null,
+  initialCharacterAnimationPanel = null,
+  initialLayers = [createLayer()],
+  projectId = undefined,
+  applyProjectSnapshot = undefined,
+}: {
+  initialDialog?: GenerateDialogState | null;
+  initialQuickEditPanel?: QuickEditPanelState | null;
+  initialCharacterAnimationPanel?: CharacterAnimationPanelState | null;
+  initialLayers?: CanvasLayer[];
+  projectId?: string | null;
+  applyProjectSnapshot?: Parameters<
+    typeof useImageCanvasGenerationSubmissionWorkflow
+  >[0]['applyProjectSnapshot'];
+}) {
+  const [layers, setLayers] = useState<CanvasLayer[]>(initialLayers);
+  const [activeTool, setActiveTool] = useState<CanvasTool>('generate');
+  const [activeSidebarPanel, setActiveSidebarPanel] =
+    useState<SidebarPanel | null>('assets');
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
+  const [quickEditPanel, setQuickEditPanel] =
+    useState<QuickEditPanelState | null>(initialQuickEditPanel);
+  const [characterAnimationPanel, setCharacterAnimationPanel] =
+    useState<CharacterAnimationPanelState | null>(
+      initialCharacterAnimationPanel,
+    );
+  const rememberedImageModelRef = useRef<string | null>(null);
+  const fitLayersMockRef = useRef(vi.fn());
+  const layerCounterRef = useRef(0);
+  const dialogs = useCanvasGenerationDialogs();
+
+  const sourceLayer = layers[0] ?? null;
+  const quickEditSourceLayer = quickEditPanel
+    ? (layers.find((layer) => layer.id === quickEditPanel.sourceLayerId) ??
+      null)
+    : null;
+  const characterAnimationSourceLayer = characterAnimationPanel
+    ? (layers.find(
+        (layer) => layer.id === characterAnimationPanel.sourceLayerId,
+      ) ?? null)
+    : null;
+  const activeDialog = dialogs.generateDialog;
+  const activeCanvasDialog =
+    activeDialog && 'id' in activeDialog
+      ? (activeDialog as CanvasGenerationDialogState)
+      : null;
+
+  const workflow = useImageCanvasGenerationSubmissionWorkflow({
+    layers,
+    canvasSize: { width: 900, height: 640 },
+    viewport: { x: 10, y: 20, scale: 2 },
+    layerCounterRef,
+    quickEditPanel,
+    quickEditSourceLayer,
+    setQuickEditPanel,
+    characterAnimationPanel,
+    characterAnimationDialog: activeCanvasDialog,
+    characterAnimationSourceLayer,
+    setCharacterAnimationPanel,
+    setGenerateDialog: dialogs.setGenerateDialog,
+    openCanvasGenerationDialog: dialogs.openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById: dialogs.updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById: dialogs.hasCanvasGenerationDialogById,
+    getGeneratingDialogPlaceholder: dialogs.getGeneratingDialogPlaceholder,
+    appendCanvasLayersWithResources: (nextLayers) =>
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]),
+    selectSingleLayer: setSelectedLayerId,
+    fitLayers: fitLayersMockRef.current,
+    setActiveTool,
+    setActiveSidebarPanel,
+    rememberImageModel: (imageModel) => {
+      rememberedImageModelRef.current = imageModel;
+    },
+    projectId,
+    assetFolderId: projectId ? 'project' : undefined,
+    applyProjectSnapshot,
+  });
+
+  return (
+    <div>
+      <span data-testid="tool">{activeTool}</span>
+      <span data-testid="sidebar">{activeSidebarPanel ?? '-'}</span>
+      <span data-testid="selected">{selectedLayerId ?? '-'}</span>
+      <span data-testid="layers">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.title}:${layer.sourceResourceId ?? '-'}:${layer.assetKind ?? '-'}:${layer.mediaType ?? '-'}:${layer.src}:${layer.thumbnailSrc ?? '-'}:${layer.durationSeconds ?? '-'}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="dialog">
+        {activeDialog
+          ? `${activeDialog.mode}:${activeDialog.status}:${activeDialog.composerOpen !== false ? 'open' : 'closed'}:${activeDialog.generatedLayerId ?? '-'}:${activeDialog.placeholder ? 'placeholder' : '-'}:${activeDialog.errorMessage ?? '-'}`
+          : '-'}
+      </span>
+      <span data-testid="quick-edit">
+        {quickEditPanel
+          ? `${quickEditPanel.sourceLayerId}:${quickEditPanel.status}:${quickEditPanel.prompt || '-'}:${quickEditPanel.errorMessage ?? '-'}`
+          : '-'}
+      </span>
+      <span data-testid="character-animation">
+        {characterAnimationPanel
+          ? `${characterAnimationPanel.sourceLayerId}:${characterAnimationPanel.status}:${characterAnimationPanel.promptText || '-'}:${characterAnimationPanel.errorMessage ?? '-'}:${characterAnimationPanel.result ? 'result' : '-'}`
+          : '-'}
+      </span>
+      <span data-testid="fit-count">
+        {fitLayersMockRef.current.mock.calls.length}
+      </span>
+      <span data-testid="remembered-model">
+        {rememberedImageModelRef.current ?? '-'}
+      </span>
+      <button
+        type="button"
+        onClick={() => {
+          if (initialDialog) {
+            dialogs.setGenerateDialog(initialDialog);
+          }
+        }}
+      >
+        设置初始对话
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (sourceLayer) {
+            setQuickEditPanel(createQuickEditPanelDraft(sourceLayer));
+          }
+        }}
+      >
+        打开快速编辑
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setQuickEditPanel((currentPanel) =>
+            currentPanel ? { ...currentPanel, prompt: '  快速修图  ' } : null,
+          )
+        }
+      >
+        填写快速编辑
+      </button>
+      <button type="button" onClick={() => void workflow.submitQuickEdit()}>
+        提交快速编辑
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (activeDialog) {
+            void workflow.submitImageGeneration(activeDialog);
+          }
+        }}
+      >
+        提交当前生成
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (activeDialog) {
+            void workflow.submitIconSpritesheetGeneration(activeDialog);
+          }
+        }}
+      >
+        提交图标
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (sourceLayer) {
+            void workflow.extractUiDesignAssets(sourceLayer);
+          }
+        }}
+      >
+        提取UI素材
+      </button>
+      <button
+        type="button"
+        onClick={() => void workflow.submitCharacterAnimation()}
+      >
+        提交角色动画
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (activeCanvasDialog) {
+            dialogs.updateCanvasGenerationDialogById(
+              activeCanvasDialog.id,
+              (dialog) => ({
+                ...dialog,
+                placeholder: dialog.placeholder
+                  ? { ...dialog.placeholder, x: 500, y: 400 }
+                  : dialog.placeholder,
+              }),
+            );
+          }
+        }}
+      >
+        移动占位
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasGenerationSubmissionWorkflow', () => {
+  beforeEach(() => {
+    resolveEditorImageReferenceDataUrlMock.mockReset();
+    resolveEditorImageReferenceDataUrlForGenerationMock.mockReset();
+    editEditorImageMock.mockReset();
+    extractEditorUiDesignAssetsMock.mockReset();
+    generateEditorCharacterAnimationMock.mockReset();
+    generateEditorIconSpritesheetMock.mockReset();
+    generateEditorImageMock.mockReset();
+    generateEditorVideoMock.mockReset();
+    resolveEditorImageReferenceDataUrlMock.mockImplementation(
+      async (src: string) => `data:image/png;base64,${src.split('/').pop()}`,
+    );
+    resolveEditorImageReferenceDataUrlForGenerationMock.mockImplementation(
+      async (src: string) => src,
+    );
+  });
+
+  it('submits quick edits, clears the panel, and fits the source plus result', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '快速修图' }),
+    );
+    render(<SubmissionWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开快速编辑' }));
+    fireEvent.click(screen.getByRole('button', { name: '填写快速编辑' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    expect(screen.getByTestId('quick-edit').textContent).toBe('-');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'quick-edit:generating:closed:-:placeholder:-',
+    );
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '快速修图',
+          size: '1024x768',
+          aspectRatio: '4:3',
+          imageSize: '1K',
+          kind: 'quick-edit',
+          model: 'gemini-3.1-flash-image-preview',
+          referenceImageSrcs: ['data:image/png;base64,source.png'],
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-quick-edit-1:源图 快速编辑:resource-source:-',
+      );
+    });
+    expect(screen.getByTestId('quick-edit').textContent).toBe('-');
+    expect(screen.getByTestId('tool').textContent).toBe('select');
+    expect(screen.getByTestId('sidebar').textContent).toBe('layers');
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-quick-edit-1',
+    );
+    expect(screen.getByTestId('fit-count').textContent).toBe('1');
+  });
+
+  it('keeps failed quick edit panels visible with the normalized prompt', async () => {
+    generateEditorImageMock.mockRejectedValueOnce(new Error('修图失败'));
+    render(
+      <SubmissionWorkflowHarness
+        initialQuickEditPanel={{
+          sourceLayerId: 'layer-source',
+          prompt: '',
+          size: '1024x768',
+          model: 'gpt-image-2',
+          status: 'idle',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('quick-edit').textContent).toBe(
+        'layer-source:failed:快速编辑图片:修图失败',
+      );
+    });
+  });
+
+  it('submits character redraws through the character image prompt contract', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '角色换成蓝色披风' }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            assetKind: 'character',
+            prompt: '原始角色设定',
+          }),
+        ]}
+        initialQuickEditPanel={{
+          mode: 'redraw',
+          sourceLayerId: 'layer-source',
+          prompt: '  角色换成蓝色披风  ',
+          size: '1024x768',
+          model: 'gpt-image-2',
+          status: 'idle',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '角色换成蓝色披风',
+          size: '1024x768',
+          aspectRatio: '4:3',
+          imageSize: '1K',
+          kind: 'character',
+          model: 'gpt-image-2',
+          referenceImageSrcs: ['data:image/png;base64,source.png'],
+          assetKind: 'character',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-quick-edit-1:源图 重绘:resource-source:character',
+      );
+    });
+    expect(screen.getByTestId('quick-edit').textContent).toBe(
+      'layer-source:idle:角色换成蓝色披风:-',
+    );
+  });
+
+  it('submits video quick edits through the video API with the source video as the hidden last reference', async () => {
+    generateEditorVideoMock.mockResolvedValueOnce(
+      createVideoGenerated({ prompt: '把图2改成雨天' }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            title: '源视频',
+            src: 'https://assets.example.test/source.mp4',
+            objectKey: 'generated-character-drafts/editor/videos/source.mp4',
+            mediaType: 'video',
+            assetKind: 'video',
+            model: 'gpt-image-2',
+            originalWidth: 854,
+            originalHeight: 480,
+            width: 427,
+            height: 240,
+          }),
+        ]}
+        initialQuickEditPanel={{
+          mode: 'quick-edit',
+          sourceLayerId: 'layer-source',
+          prompt: '把当前图改成雨天',
+          size: '854x480',
+          model: 'gpt-image-2',
+          status: 'idle',
+          quickEditReferences: [
+            {
+              id: 'ref-style',
+              label: '风格参考',
+              src: 'https://assets.example.test/style.png',
+            },
+          ],
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    await waitFor(() => {
+      expect(generateEditorVideoMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '把图2改成雨天',
+          model: 'seedance2.0-fast',
+          aspectRatio: '16:9',
+          durationSeconds: 4,
+          resolution: '480p',
+          mode: 'std',
+          sound: 'off',
+          priceMudPoints: 40,
+          referenceImageSrcs: ['data:image/png;base64,style.png'],
+          referenceVideoSrcs: [
+            'generated-character-drafts/editor/videos/source.mp4',
+          ],
+        }),
+      );
+    });
+    expect(generateEditorImageMock).not.toHaveBeenCalled();
+    expect(generateEditorCharacterAnimationMock).not.toHaveBeenCalled();
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-video-1:源视频 快速编辑:resource-source:video:video:https://assets.example.test/generated-video.mp4',
+      );
+    });
+  });
+
+  it('submits character action quick edits through seedance fast character animation generation', async () => {
+    generateEditorCharacterAnimationMock.mockResolvedValueOnce({
+      taskId: 'action-quick-edit-task',
+      model: 'seedance2.0-fast',
+      prompt: '让图1跳得更高',
+      previewVideoPath: '/generated-character-drafts/editor/action-preview.mp4',
+      frames: [
+        {
+          frameIndex: 1,
+          imageSrc: 'data:image/png;base64,action-frame-edited',
+          width: 1024,
+          height: 1024,
+        },
+      ],
+      frameCount: 32,
+      durationSeconds: 4,
+      fps: 8,
+      priceMudPoints: 40,
+    });
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            title: '角色动作',
+            src: 'https://assets.example.test/action-preview.mp4',
+            mediaType: 'video',
+            thumbnailSrc:
+              'generated-character-drafts/editor/actions/frame.png',
+            assetKind: 'character-animation',
+            model: 'seedance2.0',
+            originalWidth: 1024,
+            originalHeight: 1024,
+            width: 420,
+            height: 420,
+          }),
+        ]}
+        initialQuickEditPanel={{
+          mode: 'quick-edit',
+          sourceLayerId: 'layer-source',
+          prompt: '让当前图跳得更高',
+          size: '1024x1024',
+          model: 'gpt-image-2',
+          status: 'idle',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    await waitFor(() => {
+      expect(generateEditorCharacterAnimationMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceLayerId: 'layer-source',
+          sourceImageSrc: 'generated-character-drafts/editor/actions/frame.png',
+          promptText: '让图1跳得更高',
+          resolution: '480p',
+          ratio: 'same',
+          frameCount: 32,
+          durationSeconds: 4,
+          priceMudPoints: 40,
+          model: 'seedance2.0-fast',
+        }),
+      );
+    });
+    expect(generateEditorImageMock).not.toHaveBeenCalled();
+    expect(generateEditorVideoMock).not.toHaveBeenCalled();
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-character-animation-1:角色动作 快速编辑:resource-source:character-animation:video:/generated-character-drafts/editor/action-preview.mp4:data:image/png;base64,action-frame-edited:4',
+      );
+    });
+  });
+
+  it('submits edit dialogs beside the source and clears the modal state', async () => {
+    editEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '修改当前图片' }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          mode: 'edit',
+          prompt: '',
+          status: 'idle',
+          sourceLayerId: 'layer-source',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'edit:generating:open:-:-:-',
+    );
+    await waitFor(() => {
+      expect(editEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '修改当前图片',
+          sourceImageSrc: 'data:image/png;base64,source.png',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-edit-1:源图 修改结果:resource-source:-',
+      );
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+    expect(screen.getByTestId('tool').textContent).toBe('select');
+    expect(screen.getByTestId('fit-count').textContent).toBe('1');
+  });
+
+  it('uses the latest moved canvas placeholder for local-only generation fallback', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ width: 512, height: 512 }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-1',
+          mode: 'generate',
+          prompt: '占位生成',
+          status: 'idle',
+          composerOpen: true,
+          placeholder: {
+            x: 100,
+            y: 100,
+            width: 420,
+            height: 420,
+            originalWidth: 2048,
+            originalHeight: 2048,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '移动占位' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-generated-1:生成图片 1:-:-',
+      );
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:idle:open:layer-generated-1:placeholder:-',
+    );
+  });
+
+  it('passes canvas completion context and refreshes from the backend project snapshot', async () => {
+    const applyProjectSnapshot = vi.fn();
+    generateEditorImageMock.mockResolvedValueOnce({
+      ...createGenerated({
+        width: 1024,
+        height: 1024,
+        prompt: '银发游侠',
+      }),
+      project: {
+        projectId: 'editor-project-1',
+        title: '角色项目',
+        viewport: { x: 12, y: 24, scale: 1.5 },
+        layers: [
+          {
+            layerId: 'layer-editor-resource-character',
+            resourceId: 'editor-resource-character',
+          },
+        ],
+        resources: [],
+        updatedAt: '2026-06-21T12:16:22.000Z',
+      },
+    });
+    render(
+      <SubmissionWorkflowHarness
+        projectId="editor-project-1"
+        applyProjectSnapshot={applyProjectSnapshot}
+        initialDialog={{
+          id: 'dialog-character',
+          mode: 'character',
+          prompt: '  银发游侠  ',
+          status: 'idle',
+          composerOpen: true,
+          imageModel: 'gpt-image-2',
+          placeholder: {
+            x: 200,
+            y: 160,
+            width: 420,
+            height: 560,
+            originalWidth: 1024,
+            originalHeight: 1536,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: '银发游侠',
+          kind: 'character',
+          projectId: 'editor-project-1',
+          assetKind: 'character',
+          assetFolderId: 'project',
+          canvasCompletion: {
+            dialogId: 'dialog-character',
+            title: '角色形象 1',
+            placeholder: {
+              x: 200,
+              y: 160,
+              width: 420,
+              height: 560,
+              originalWidth: 1024,
+              originalHeight: 1536,
+            },
+          },
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(applyProjectSnapshot).toHaveBeenCalledWith(
+        expect.objectContaining({
+          projectId: 'editor-project-1',
+          title: '角色项目',
+        }),
+      );
+    });
+    expect(screen.getByTestId('layers').textContent).not.toContain(
+      'layer-generated-1',
+    );
+  });
+
+  it('does not add a local layer when project generation returns without a backend snapshot', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({
+        width: 1024,
+        height: 1024,
+        prompt: '银发游侠',
+        project: null,
+      }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        projectId="editor-project-1"
+        initialDialog={{
+          id: 'dialog-character',
+          mode: 'character',
+          prompt: '银发游侠',
+          status: 'idle',
+          composerOpen: true,
+          imageModel: 'gpt-image-2',
+          placeholder: {
+            x: 200,
+            y: 160,
+            width: 420,
+            height: 560,
+            originalWidth: 1024,
+            originalHeight: 1536,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          projectId: 'editor-project-1',
+          canvasCompletion: expect.objectContaining({
+            dialogId: 'dialog-character',
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toBe(
+        'character:idle:open:-:placeholder:-',
+      );
+    });
+    expect(screen.getByTestId('layers').textContent).not.toContain(
+      'layer-generated-1',
+    );
+  });
+
+  it('submits publication detail materials as one billable editor image and appends the result', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({
+        imageSrc: 'data:image/png;base64,publication',
+        width: 720,
+        height: 1280,
+        prompt: '游戏名：云朵消消乐',
+      }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-publication',
+          mode: 'publication',
+          prompt: '',
+          status: 'idle',
+          composerOpen: true,
+          publicationWorkflowId: 'publication-detail-gallery',
+          publicationGameInfo: {
+            gameName: '云朵消消乐',
+            gameCategories: '休闲消除',
+            gameDescription: '点击同类云朵完成消除',
+          },
+          publicationReferences: [
+            {
+              id: 'ref-1',
+              label: '主视觉参考',
+              src: 'data:image/png;base64,large-ref',
+            },
+          ],
+          placeholder: {
+            x: 180,
+            y: 120,
+            width: 360,
+            height: 640,
+            originalWidth: 720,
+            originalHeight: 1280,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'publication:generating:closed:-:placeholder:-',
+    );
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          prompt: expect.stringContaining('【宣发素材类型】详情页单图'),
+          size: '720x1280',
+          kind: 'publication-material',
+          model: 'gemini-3.1-flash-image-preview',
+          aspectRatio: '9:16',
+          imageSize: '1K',
+          referenceImageSrcs: ['data:image/png;base64,large-ref'],
+        }),
+      );
+    });
+    const prompt = generateEditorImageMock.mock.calls[0]?.[0]?.prompt ?? '';
+    expect(prompt).toContain('游戏名：云朵消消乐');
+    expect(prompt).toContain('本次只生成一张 720 x 1280 竖版详情图');
+    expect(prompt).toContain('不是五图合集或拼贴');
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-generated-1:1 宣发素材:-:-',
+      );
+    });
+    expect(screen.getByTestId('layers').textContent).not.toContain(
+      'layer-generated-2',
+    );
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-generated-1',
+    );
+  });
+
+  it('compresses publication references before submitting generation', async () => {
+    resolveEditorImageReferenceDataUrlForGenerationMock.mockResolvedValueOnce(
+      'data:image/jpeg;base64,compressed-ref',
+    );
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({
+        imageSrc: 'data:image/png;base64,publication',
+        width: 720,
+        height: 540,
+        prompt: '游戏名：云朵消消乐',
+      }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-publication',
+          mode: 'publication',
+          prompt: '',
+          status: 'idle',
+          composerOpen: true,
+          publicationWorkflowId: 'publication-cover-image',
+          publicationGameInfo: {
+            gameName: '云朵消消乐',
+            gameCategories: '休闲消除',
+            gameDescription: '点击同类云朵完成消除',
+          },
+          publicationReferences: [
+            {
+              id: 'ref-1',
+              label: '主视觉参考',
+              src: 'data:image/png;base64,large-original-ref',
+            },
+          ],
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    await waitFor(() => {
+      expect(
+        resolveEditorImageReferenceDataUrlForGenerationMock,
+      ).toHaveBeenCalledWith('data:image/png;base64,large-original-ref');
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kind: 'publication-material',
+          aspectRatio: '4:3',
+          imageSize: '1K',
+          referenceImageSrcs: ['data:image/jpeg;base64,compressed-ref'],
+        }),
+      );
+    });
+  });
+
+  it('validates icon submission before calling the API', async () => {
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-icon',
+          mode: 'icon',
+          prompt: '  返回按钮  \n\n设置按钮',
+          status: 'idle',
+          composerOpen: true,
+          iconDescriptions: ['返回按钮'],
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交图标' }));
+
+    expect(generateEditorIconSpritesheetMock).not.toHaveBeenCalled();
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        '请选择图标规范',
+      );
+    });
+  });
+
+  it('submits icon spritesheets, trims descriptions, and remembers the model', async () => {
+    generateEditorIconSpritesheetMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,sheet',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      prompt: '图标素材',
+      actualPrompt: '图标素材',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'task-icons',
+      priceMudPoints: 20,
+      iconImageSrcs: [
+        createIconResult('返回按钮', 'data:image/png;base64,back'),
+        createIconResult('设置按钮', 'data:image/png;base64,setting'),
+      ],
+    });
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-icon',
+          mode: 'icon',
+          prompt: '  返回按钮  \n\n  设置按钮  ',
+          status: 'idle',
+          composerOpen: true,
+          imageModel: 'gpt-image-2',
+          iconSpecReference: {
+            id: 'spec',
+            label: '图标规范',
+            src: 'data:image/png;base64,spec',
+          },
+          iconDescriptions: ['旧返回', '旧设置'],
+          placeholder: {
+            x: 140,
+            y: 160,
+            width: 360,
+            height: 360,
+            originalWidth: 512,
+            originalHeight: 512,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交图标' }));
+
+    await waitFor(() => {
+      expect(generateEditorIconSpritesheetMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          referenceImageSrc: 'data:image/png;base64,spec',
+          iconDescriptions: ['返回按钮', '设置按钮'],
+          model: 'gpt-image-2',
+          priceMudPoints: 20,
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-icon-spritesheet-1:图标素材图集 1:-:icon-spritesheet',
+      );
+    });
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'layer-icon-2:返回按钮:-:icon',
+    );
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'layer-icon-3:设置按钮:-:icon',
+    );
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-icon-spritesheet-1',
+    );
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'icon:idle:open:layer-icon-spritesheet-1:placeholder:-',
+    );
+    expect(screen.getByTestId('remembered-model').textContent).toBe(
+      'gpt-image-2',
+    );
+  });
+
+  it('extracts UI design assets into a spritesheet layer and sliced icon layers', async () => {
+    extractEditorUiDesignAssetsMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,ui-sheet',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      prompt: '提取画面中的所有独立并整理成spritesheet',
+      actualPrompt: '提取画面中的所有独立并整理成spritesheet',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'task-ui-assets',
+      priceMudPoints: 20,
+      iconImageSrcs: [
+        createIconResult('素材 1', 'data:image/png;base64,asset-1'),
+      ],
+    });
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            assetKind: 'ui-design',
+            objectKey: 'generated/ui-design.png',
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提取UI素材' }));
+
+    await waitFor(() => {
+      expect(resolveEditorImageReferenceDataUrlMock).toHaveBeenCalledWith(
+        'generated/ui-design.png',
+      );
+    });
+    await waitFor(() => {
+      expect(extractEditorUiDesignAssetsMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceImageSrc: 'data:image/png;base64,ui-design.png',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-icon-spritesheet-1:源图 素材图集:-:icon-spritesheet',
+      );
+    });
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'layer-icon-2:素材 1:-:icon',
+    );
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-icon-spritesheet-1',
+    );
+    expect(screen.getByTestId('fit-count').textContent).toBe('1');
+  });
+
+  it('keeps character generation dialog data after the result is created', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ width: 768, height: 768 }),
+    );
+    render(
+      <SubmissionWorkflowHarness
+        initialDialog={{
+          id: 'dialog-character',
+          mode: 'character',
+          prompt: '骑士角色',
+          status: 'idle',
+          composerOpen: true,
+          imageModel: 'gpt-image-2',
+          characterSpecReference: {
+            id: 'spec-character',
+            label: '角色规范',
+            src: 'data:image/png;base64,spec',
+          },
+          placeholder: {
+            x: 120,
+            y: 140,
+            width: 420,
+            height: 420,
+            originalWidth: 2048,
+            originalHeight: 2048,
+          },
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交当前生成' }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-generated-1:角色形象 1:-:character',
+      );
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character:idle:open:layer-generated-1:placeholder:-',
+    );
+  });
+
+  it('moves character animation panels from generating to completed', async () => {
+    generateEditorCharacterAnimationMock.mockResolvedValueOnce({
+      frames: [{ imageSrc: 'data:image/png;base64,frame' }],
+      previewSrc: 'data:image/png;base64,preview',
+      taskId: 'animation-task',
+    });
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            id: 'character-layer',
+            assetKind: 'character',
+            objectKey: 'generated/character.png',
+          }),
+        ]}
+        initialCharacterAnimationPanel={{
+          sourceLayerId: 'character-layer',
+          promptText: '  跑步  ',
+          resolution: '480p',
+          ratio: 'same',
+          frameCount: 32,
+          durationSeconds: 4,
+          status: 'idle',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '提交角色动画' }));
+
+    expect(screen.getByTestId('character-animation').textContent).toBe(
+      'character-layer:generating:跑步:-:-',
+    );
+    await waitFor(() => {
+      expect(generateEditorCharacterAnimationMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceLayerId: 'character-layer',
+          sourceImageSrc: 'generated/character.png',
+          promptText: '跑步',
+          model: 'seedance2.0-fast',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('character-animation').textContent).toBe(
+        'character-layer:completed:跑步:-:result',
+      );
+    });
+  });
+
+  it('creates an action layer for dialog-driven character animation submissions', async () => {
+    generateEditorCharacterAnimationMock.mockResolvedValueOnce({
+      taskId: 'animation-task-dialog',
+      model: 'seedance2.0-fast',
+      prompt: '挥手动作',
+      previewVideoPath: '/generated-character-drafts/editor/preview.mp4',
+      frames: [
+        {
+          frameIndex: 1,
+          imageSrc: 'data:image/png;base64,action-frame',
+          width: 1024,
+          height: 1024,
+        },
+      ],
+      frameCount: 32,
+      durationSeconds: 4,
+      fps: 8,
+      priceMudPoints: 40,
+    });
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[
+          createLayer({
+            id: 'character-layer',
+            title: '角色源图',
+            assetKind: 'character',
+            objectKey: 'generated/character.png',
+          }),
+        ]}
+        initialDialog={{
+          id: 'dialog-character-animation',
+          mode: 'character-animation',
+          sourceLayerId: 'character-layer',
+          prompt: '  挥手动作  ',
+          status: 'idle',
+          composerOpen: true,
+          characterAnimationResolution: '480p',
+          characterAnimationRatio: 'same',
+          characterAnimationFrameCount: 32,
+          characterAnimationDurationSeconds: 4,
+          placeholder: {
+            x: 80,
+            y: 60,
+            width: 420,
+            height: 420,
+            originalWidth: 1024,
+            originalHeight: 1024,
+          },
+        }}
+        initialCharacterAnimationPanel={{
+          sourceLayerId: 'character-layer',
+          promptText: '  挥手动作  ',
+          resolution: '480p',
+          ratio: 'same',
+          frameCount: 32,
+          durationSeconds: 4,
+          status: 'idle',
+        }}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '设置初始对话' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交角色动画' }));
+
+    await waitFor(() => {
+      expect(generateEditorCharacterAnimationMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceLayerId: 'character-layer',
+          sourceImageSrc: 'generated/character.png',
+          promptText: '挥手动作',
+          model: 'seedance2.0-fast',
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-character-animation-1:角色动作:resource-source:character-animation:video:/generated-character-drafts/editor/preview.mp4:data:image/png;base64,action-frame:4',
+      );
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character-animation:idle:open:layer-character-animation-1:placeholder:-',
+    );
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-character-animation-1',
+    );
+  });
+
+  it('uses a fallback error message for failed character animation submissions', async () => {
+    generateEditorCharacterAnimationMock.mockRejectedValueOnce(new Error(''));
+    render(
+      <SubmissionWorkflowHarness
+        initialLayers={[createLayer({ id: 'character-layer' })]}
+        initialCharacterAnimationPanel={{
+          sourceLayerId: 'character-layer',
+          promptText: '',
+          resolution: '480p',
+          ratio: 'same',
+          frameCount: 32,
+          durationSeconds: 4,
+          status: 'idle',
+        }}
+      />,
+    );
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '提交角色动画' }));
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('character-animation').textContent).toBe(
+        'character-layer:failed:-:生成角色动画失败:-',
+      );
+    });
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
new file mode 100644
index 000000000..d8ec39135
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts
@@ -0,0 +1,1212 @@
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+} from 'react';
+
+import {
+  resolveEditorImageReferenceDataUrl,
+  resolveEditorImageReferenceDataUrlForGeneration,
+} from '../../services/image-editor/editorImageReference';
+import type {
+  EditorAssetSnapshot,
+  EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import {
+  editEditorImage,
+  extractEditorUiDesignAssets,
+  generateEditorBackgroundMusic,
+  generateEditorCharacterAnimation,
+  generateEditorIconSpritesheet,
+  generateEditorImage,
+  generateEditorSoundEffect,
+  generateEditorVideo,
+} from '../../services/image-editor/editorProjectClient';
+import type {
+  CanvasGenerationDialogState,
+  CanvasGenerationInputs,
+  CanvasLayer,
+  CanvasTool,
+  CanvasViewport,
+  CharacterAnimationPanelState,
+  GenerateDialogState,
+  QuickEditPanelState,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+import { createQuickEditGenerationDialogDraft } from './ImageCanvasGenerationDialogModel';
+import {
+  createAudioResultLayer,
+  createCharacterAnimationResultLayer,
+  createGeneratedResultLayer,
+  createIconSpritesheetResultLayers,
+  createQuickEditResultLayer,
+  createVideoResultLayer,
+} from './ImageCanvasGenerationLayerModel';
+import {
+  buildCharacterAnimationGenerationInputs,
+  buildEditGenerationInputs,
+  buildQuickEditGenerationInputs,
+  buildUiDesignAssetExtractionGenerationInputs,
+  buildVideoGenerationInputs,
+  calculateCharacterAnimationPrice,
+  calculateEditorVideoPrice,
+  CHARACTER_ANIMATION_MODEL,
+  DEFAULT_VIDEO_MODEL,
+  ICON_FRAME_DISPLAY_SIZE,
+  ICON_FRAME_ORIGINAL_SIZE,
+  inferEditorImageAspectRatio,
+  inferEditorImageSizeLabel,
+  isCanvasGenerationDialog,
+  normalizeEditorImageModel,
+  normalizeQuickEditPromptSourceReference,
+  resolveCharacterAnimationSourceImageSrc,
+  resolveEditorImageGenerationPixelSize,
+  resolveImageGenerationErrorMessage,
+} from './ImageCanvasGenerationModel';
+import {
+  buildCharacterAnimationSubmissionPlan,
+  buildIconSpritesheetGenerationSubmissionPlan,
+  buildImageGenerationSubmissionPlan,
+} from './ImageCanvasGenerationSubmissionModel';
+
+type CanvasSize = { width: number; height: number };
+
+type CanvasGenerationDialogUpdater = (
+  dialog: CanvasGenerationDialogState,
+) => CanvasGenerationDialogState | null;
+
+type GenerationSubmissionWorkflowOptions = {
+  layers: CanvasLayer[];
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  layerCounterRef: MutableRefObject<number>;
+  quickEditPanel: QuickEditPanelState | null;
+  quickEditSourceLayer: CanvasLayer | null;
+  setQuickEditPanel: Dispatch<SetStateAction<QuickEditPanelState | null>>;
+  characterAnimationPanel: CharacterAnimationPanelState | null;
+  characterAnimationDialog: CanvasGenerationDialogState | null;
+  characterAnimationSourceLayer: CanvasLayer | null;
+  setCharacterAnimationPanel: Dispatch<
+    SetStateAction<CharacterAnimationPanelState | null>
+  >;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  openCanvasGenerationDialog: (
+    dialog: Omit<CanvasGenerationDialogState, 'id'>,
+  ) => string;
+  updateCanvasGenerationDialogById: (
+    dialogId: string,
+    updater: CanvasGenerationDialogUpdater,
+  ) => void;
+  hasCanvasGenerationDialogById: (dialogId: string) => boolean;
+  getGeneratingDialogPlaceholder: (
+    dialog: GenerateDialogState,
+  ) => GenerateDialogState['placeholder'];
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  fitLayers: (targetLayers?: CanvasLayer[]) => void;
+  setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
+  setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
+  rememberImageModel: (imageModel: string) => void;
+  projectId?: string | null;
+  assetFolderId?: string | null;
+  upsertGeneratedAsset?: (asset: EditorAssetSnapshot) => void;
+  applyProjectSnapshot?: (project: EditorProjectSnapshot) => void;
+};
+
+async function normalizePublicationReferenceImages(
+  input: Parameters<typeof generateEditorImage>[0],
+) {
+  if (
+    input.kind !== 'publication-material' ||
+    !input.referenceImageSrcs?.length
+  ) {
+    return input;
+  }
+
+  return {
+    ...input,
+    referenceImageSrcs: await Promise.all(
+      input.referenceImageSrcs.map((referenceImageSrc) =>
+        resolveEditorImageReferenceDataUrlForGeneration(referenceImageSrc),
+      ),
+    ),
+  };
+}
+
+function isVideoQuickEditSource(layer: CanvasLayer) {
+  return layer.mediaType === 'video' || layer.assetKind === 'video';
+}
+
+function isCharacterAnimationQuickEditSource(layer: CanvasLayer) {
+  return layer.assetKind === 'character-animation';
+}
+
+export function useImageCanvasGenerationSubmissionWorkflow({
+  layers,
+  canvasSize,
+  viewport,
+  layerCounterRef,
+  quickEditPanel,
+  quickEditSourceLayer,
+  setQuickEditPanel,
+  characterAnimationPanel,
+  characterAnimationDialog,
+  characterAnimationSourceLayer,
+  setCharacterAnimationPanel,
+  setGenerateDialog,
+  openCanvasGenerationDialog,
+  updateCanvasGenerationDialogById,
+  hasCanvasGenerationDialogById,
+  getGeneratingDialogPlaceholder,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+  fitLayers,
+  setActiveTool,
+  setActiveSidebarPanel,
+  rememberImageModel,
+  projectId,
+  assetFolderId,
+  upsertGeneratedAsset,
+  applyProjectSnapshot,
+}: GenerationSubmissionWorkflowOptions) {
+  const addGeneratedLayersToCanvas = useCallback(
+    (nextLayers: CanvasLayer[]) => {
+      appendCanvasLayersWithResources(nextLayers);
+      nextLayers.forEach((layer) => {
+        const asset = layer.generatedAssetSnapshot;
+        if (asset) {
+          upsertGeneratedAsset?.(asset);
+        }
+      });
+    },
+    [appendCanvasLayersWithResources, upsertGeneratedAsset],
+  );
+
+  const addGeneratedResultLayer = useCallback(
+    (
+      generated: Parameters<typeof createGeneratedResultLayer>[0]['generated'],
+      options: {
+        sourceLayer?: CanvasLayer;
+        frame?: GenerateDialogState['placeholder'];
+        assetKind?: CanvasLayer['assetKind'];
+        title?: string;
+        dialogId?: string;
+        generationInputs?: CanvasGenerationInputs;
+      } = {},
+    ) => {
+      if (options.dialogId && !hasCanvasGenerationDialogById(options.dialogId)) {
+        return;
+      }
+      layerCounterRef.current += 1;
+      const generatedIndex = layerCounterRef.current;
+      const nextLayer = createGeneratedResultLayer({
+        generated,
+        generatedIndex,
+        canvasSize,
+        viewport,
+        sourceLayer: options.sourceLayer,
+        frame: options.frame,
+        assetKind: options.assetKind,
+        title: options.title,
+        generationInputs: options.generationInputs,
+      });
+
+      addGeneratedLayersToCanvas([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setActiveSidebarPanel('layers');
+      if (options.sourceLayer) {
+        setGenerateDialog(null);
+        setActiveTool('select');
+      } else if (options.dialogId) {
+        updateCanvasGenerationDialogById(options.dialogId, (currentDialog) => ({
+          ...currentDialog,
+          status: 'idle',
+          composerOpen: true,
+          generatedLayerId: nextLayer.id,
+          errorMessage: undefined,
+        }));
+      }
+      if (options.sourceLayer) {
+        fitLayers([options.sourceLayer, nextLayer]);
+      }
+    },
+    [
+      addGeneratedLayersToCanvas,
+      canvasSize,
+      fitLayers,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      setGenerateDialog,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+      viewport,
+    ],
+  );
+
+  const addQuickEditResultLayer = useCallback(
+    (
+      generated: Parameters<typeof createQuickEditResultLayer>[0]['generated'],
+      sourceLayer: CanvasLayer,
+      generationInputs: CanvasGenerationInputs,
+      mode: QuickEditPanelState['mode'] = 'quick-edit',
+      options: {
+        frame?: GenerateDialogState['placeholder'];
+        dialogId?: string;
+      } = {},
+    ) => {
+      if (options.dialogId && !hasCanvasGenerationDialogById(options.dialogId)) {
+        return;
+      }
+      layerCounterRef.current += 1;
+      const generatedIndex = layerCounterRef.current;
+      const nextLayer = createQuickEditResultLayer({
+        generated,
+        generatedIndex,
+        sourceLayer,
+        generationInputs,
+        mode,
+        frame: options.frame,
+      });
+
+      addGeneratedLayersToCanvas([nextLayer]);
+      selectSingleLayer(mode === 'redraw' ? sourceLayer.id : nextLayer.id);
+      setActiveSidebarPanel('layers');
+      if (mode === 'redraw') {
+        setQuickEditPanel((currentPanel) =>
+          currentPanel?.sourceLayerId === sourceLayer.id
+            ? {
+                ...currentPanel,
+                mode: 'redraw',
+                status: 'idle',
+                errorMessage: undefined,
+              }
+            : currentPanel,
+        );
+      } else {
+        setQuickEditPanel(null);
+        setActiveTool('select');
+        if (options.dialogId) {
+          updateCanvasGenerationDialogById(options.dialogId, (currentDialog) => ({
+            ...currentDialog,
+            status: 'idle',
+            composerOpen: false,
+            generatedLayerId: nextLayer.id,
+            errorMessage: undefined,
+          }));
+        }
+      }
+      fitLayers([sourceLayer, nextLayer]);
+    },
+    [
+      addGeneratedLayersToCanvas,
+      fitLayers,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      setQuickEditPanel,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+    ],
+  );
+
+  const addIconSpritesheetResultLayers = useCallback(
+    (
+      generated: Parameters<
+        typeof createIconSpritesheetResultLayers
+      >[0]['generated'],
+      iconResults: Parameters<
+        typeof createIconSpritesheetResultLayers
+      >[0]['iconResults'],
+      generationInputs: CanvasGenerationInputs,
+      frame?: GenerateDialogState['placeholder'],
+      dialogId?: string,
+      options: {
+        spritesheetTitle?: string;
+      } = {},
+    ) => {
+      if (dialogId && !hasCanvasGenerationDialogById(dialogId)) {
+        return [];
+      }
+      const startIndex = layerCounterRef.current + 1;
+      const nextLayers = createIconSpritesheetResultLayers({
+        generated,
+        iconResults,
+        startIndex,
+        canvasSize,
+        viewport,
+        generationInputs,
+        frame,
+        spritesheetTitle: options.spritesheetTitle,
+      });
+
+      if (!nextLayers.length) {
+        return [];
+      }
+      layerCounterRef.current += nextLayers.length;
+      addGeneratedLayersToCanvas(nextLayers);
+      selectSingleLayer(nextLayers[0]?.id ?? null);
+      setActiveSidebarPanel('layers');
+      if (dialogId) {
+        updateCanvasGenerationDialogById(dialogId, (currentDialog) => ({
+          ...currentDialog,
+          status: 'idle',
+          composerOpen: true,
+          generatedLayerId: nextLayers[0]?.id,
+          errorMessage: undefined,
+        }));
+      }
+      setActiveTool('select');
+      return nextLayers;
+    },
+    [
+      addGeneratedLayersToCanvas,
+      canvasSize,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+      viewport,
+    ],
+  );
+
+  const addVideoResultLayer = useCallback(
+    (
+      generated: Parameters<typeof createVideoResultLayer>[0]['generated'],
+      title: string,
+      generationInputs: CanvasGenerationInputs,
+      frame?: GenerateDialogState['placeholder'],
+      dialogId?: string,
+      options: {
+        sourceLayer?: CanvasLayer;
+        assetKind?: CanvasLayer['assetKind'];
+      } = {},
+    ) => {
+      if (dialogId && !hasCanvasGenerationDialogById(dialogId)) {
+        return;
+      }
+      layerCounterRef.current += 1;
+      const generatedIndex = layerCounterRef.current;
+      const nextLayer = createVideoResultLayer({
+        generated,
+        generatedIndex,
+        title,
+        canvasSize,
+        viewport,
+        generationInputs,
+        frame,
+        sourceLayer: options.sourceLayer,
+        assetKind: options.assetKind,
+      });
+
+      addGeneratedLayersToCanvas([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setActiveSidebarPanel('layers');
+      if (dialogId) {
+        updateCanvasGenerationDialogById(dialogId, (currentDialog) => ({
+          ...currentDialog,
+          status: 'idle',
+          composerOpen: true,
+          generatedLayerId: nextLayer.id,
+          errorMessage: undefined,
+        }));
+      }
+      setActiveTool('select');
+    },
+    [
+      addGeneratedLayersToCanvas,
+      canvasSize,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+      viewport,
+    ],
+  );
+
+  const addAudioResultLayer = useCallback(
+    (
+      generated: Parameters<typeof createAudioResultLayer>[0]['generated'],
+      title: string,
+      generationInputs: CanvasGenerationInputs,
+      frame?: GenerateDialogState['placeholder'],
+      dialogId?: string,
+    ) => {
+      if (dialogId && !hasCanvasGenerationDialogById(dialogId)) {
+        return;
+      }
+      layerCounterRef.current += 1;
+      const generatedIndex = layerCounterRef.current;
+      const nextLayer = createAudioResultLayer({
+        generated,
+        generatedIndex,
+        title,
+        canvasSize,
+        viewport,
+        generationInputs,
+        frame,
+      });
+
+      addGeneratedLayersToCanvas([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setActiveSidebarPanel('layers');
+      if (dialogId) {
+        updateCanvasGenerationDialogById(dialogId, (currentDialog) => ({
+          ...currentDialog,
+          status: 'idle',
+          composerOpen: true,
+          generatedLayerId: nextLayer.id,
+          errorMessage: undefined,
+        }));
+      }
+      setActiveTool('select');
+    },
+    [
+      addGeneratedLayersToCanvas,
+      canvasSize,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+      viewport,
+    ],
+  );
+
+  const addCharacterAnimationResultLayer = useCallback(
+    (
+      generated: Parameters<
+        typeof createCharacterAnimationResultLayer
+      >[0]['generated'],
+      title: string,
+      generationInputs: CanvasGenerationInputs,
+      frame?: GenerateDialogState['placeholder'],
+      dialogId?: string,
+      options: {
+        sourceLayer?: CanvasLayer;
+      } = {},
+    ) => {
+      if (dialogId && !hasCanvasGenerationDialogById(dialogId)) {
+        return;
+      }
+      layerCounterRef.current += 1;
+      const generatedIndex = layerCounterRef.current;
+      const nextLayer = createCharacterAnimationResultLayer({
+        generated,
+        generatedIndex,
+        title,
+        canvasSize,
+        viewport,
+        generationInputs,
+        frame,
+        sourceLayer: options.sourceLayer,
+      });
+
+      if (!nextLayer) {
+        return;
+      }
+      addGeneratedLayersToCanvas([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setActiveSidebarPanel('layers');
+      if (dialogId) {
+        updateCanvasGenerationDialogById(dialogId, (currentDialog) => ({
+          ...currentDialog,
+          status: 'idle',
+          composerOpen: true,
+          generatedLayerId: nextLayer.id,
+          characterAnimationResult: generated,
+          errorMessage: undefined,
+        }));
+      }
+      setActiveTool('select');
+    },
+    [
+      addGeneratedLayersToCanvas,
+      canvasSize,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveSidebarPanel,
+      setActiveTool,
+      updateCanvasGenerationDialogById,
+      hasCanvasGenerationDialogById,
+      viewport,
+    ],
+  );
+
+  const extractUiDesignAssets = useCallback(
+    async (sourceLayer: CanvasLayer) => {
+      if (sourceLayer.assetKind !== 'ui-design') {
+        return;
+      }
+
+      try {
+        const sourceImageSrc = await resolveEditorImageReferenceDataUrl(
+          sourceLayer.objectKey?.trim() || sourceLayer.src,
+        );
+        const generationInputs =
+          buildUiDesignAssetExtractionGenerationInputs(sourceLayer);
+        const generated = await extractEditorUiDesignAssets({
+          sourceImageSrc,
+          projectId,
+          generationInputs,
+          assetFolderId,
+          spritesheetLabel: `${sourceLayer.title} 素材图集`,
+        });
+        const extractionFrame = {
+          x: sourceLayer.x + sourceLayer.width + 32,
+          y: sourceLayer.y,
+          width: ICON_FRAME_DISPLAY_SIZE.width,
+          height: ICON_FRAME_DISPLAY_SIZE.height,
+          originalWidth: ICON_FRAME_ORIGINAL_SIZE.width,
+          originalHeight: ICON_FRAME_ORIGINAL_SIZE.height,
+        };
+        const nextLayers = addIconSpritesheetResultLayers(
+          generated,
+          generated.iconImageSrcs,
+          generationInputs,
+          extractionFrame,
+          undefined,
+          {
+            spritesheetTitle: `${sourceLayer.title} 素材图集`,
+          },
+        );
+        if (nextLayers.length) {
+          fitLayers([sourceLayer, ...nextLayers]);
+        }
+      } catch (error) {
+        window.alert(
+          error instanceof Error && error.message.trim()
+            ? error.message
+            : '提取素材失败',
+        );
+      }
+    },
+    [addIconSpritesheetResultLayers, fitLayers, projectId, assetFolderId],
+  );
+
+  const submitIconSpritesheetGeneration = useCallback(
+    async (dialog: GenerateDialogState) => {
+      if (dialog.mode !== 'icon') {
+        return;
+      }
+      const canvasDialog = isCanvasGenerationDialog(dialog) ? dialog : null;
+      const setSubmittingIconDialog = (
+        nextDialog: CanvasGenerationDialogState,
+      ) => {
+        updateCanvasGenerationDialogById(nextDialog.id, () => nextDialog);
+      };
+      const submissionPlan =
+        buildIconSpritesheetGenerationSubmissionPlan(dialog);
+      if (submissionPlan.ok === false) {
+        if (canvasDialog) {
+          setSubmittingIconDialog({
+            ...canvasDialog,
+            status: 'failed',
+            composerOpen: true,
+            errorMessage: submissionPlan.errorMessage,
+          });
+        }
+        return;
+      }
+
+      if (!canvasDialog) {
+        return;
+      }
+
+      setSubmittingIconDialog({
+        ...canvasDialog,
+        iconDescriptions: submissionPlan.iconDescriptions,
+        status: 'generating',
+        composerOpen: false,
+        errorMessage: undefined,
+      });
+
+      try {
+        const generated = await generateEditorIconSpritesheet({
+          ...submissionPlan.input,
+          projectId,
+          generationInputs: submissionPlan.generationInputs,
+          assetFolderId,
+        });
+        rememberImageModel(submissionPlan.rememberImageModel);
+        addIconSpritesheetResultLayers(
+          generated,
+          generated.iconImageSrcs,
+          submissionPlan.generationInputs,
+          getGeneratingDialogPlaceholder(dialog),
+          canvasDialog.id,
+        );
+      } catch (error) {
+        setSubmittingIconDialog({
+          ...canvasDialog,
+          iconDescriptions: submissionPlan.iconDescriptions,
+          status: 'failed',
+          composerOpen: true,
+          errorMessage: resolveImageGenerationErrorMessage(error),
+        });
+      }
+    },
+    [
+      addIconSpritesheetResultLayers,
+      getGeneratingDialogPlaceholder,
+      rememberImageModel,
+      projectId,
+      assetFolderId,
+      updateCanvasGenerationDialogById,
+    ],
+  );
+
+  const submitQuickEdit = useCallback(async () => {
+    if (!quickEditPanel || !quickEditSourceLayer) {
+      return;
+    }
+
+    const panelMode = quickEditPanel.mode ?? 'quick-edit';
+    const quickEditReferences =
+      panelMode === 'redraw' ? [] : (quickEditPanel.quickEditReferences ?? []);
+    const sourceReferenceIndex = quickEditReferences.length + 1;
+    const quickEditAspectRatio =
+      quickEditPanel.aspectRatio ??
+      inferEditorImageAspectRatio(
+        quickEditSourceLayer.originalWidth,
+        quickEditSourceLayer.originalHeight,
+      );
+    const quickEditImageSize =
+      quickEditPanel.imageSize ??
+      inferEditorImageSizeLabel(
+        quickEditSourceLayer.originalWidth,
+        quickEditSourceLayer.originalHeight,
+      );
+    const quickEditOutputSize = resolveEditorImageGenerationPixelSize({
+      model: quickEditPanel.model,
+      aspectRatio: quickEditAspectRatio,
+      imageSize: quickEditImageSize,
+    });
+    const quickEditSize = `${quickEditOutputSize.width}x${quickEditOutputSize.height}`;
+    const basePrompt =
+      quickEditPanel.prompt.trim() ||
+      (panelMode === 'redraw' ? '重绘图片' : '快速编辑图片');
+    const normalizedPrompt =
+      panelMode === 'redraw'
+        ? basePrompt
+        : normalizeQuickEditPromptSourceReference(
+            basePrompt,
+            sourceReferenceIndex,
+          );
+    let quickEditDialogId: string | undefined;
+    if (panelMode === 'quick-edit') {
+      quickEditDialogId = openCanvasGenerationDialog(
+        createQuickEditGenerationDialogDraft({
+          sourceLayer: quickEditSourceLayer,
+          prompt: normalizedPrompt,
+          status: 'generating',
+          references: quickEditReferences,
+          model: quickEditPanel.model,
+          aspectRatio: quickEditAspectRatio,
+          imageSize: quickEditImageSize,
+          frame: {
+            width: quickEditOutputSize.width,
+            height: quickEditOutputSize.height,
+          },
+        }),
+      );
+      setQuickEditPanel(null);
+      selectSingleLayer(null);
+    } else {
+      setQuickEditPanel({
+        ...quickEditPanel,
+        aspectRatio: quickEditAspectRatio,
+        imageSize: quickEditImageSize,
+        size: quickEditSize,
+        prompt: normalizedPrompt,
+        status: 'generating',
+        errorMessage: undefined,
+      });
+    }
+
+    try {
+      const extraReferenceImageSrcs = await Promise.all(
+        quickEditReferences.map((reference) =>
+          resolveEditorImageReferenceDataUrl(
+            reference.objectKey?.trim() || reference.src,
+          ),
+        ),
+      );
+      const quickEditFrame = quickEditDialogId
+        ? getGeneratingDialogPlaceholder({
+            id: quickEditDialogId,
+            mode: 'quick-edit',
+            prompt: normalizedPrompt,
+            status: 'generating',
+          })
+        : undefined;
+      if (
+        panelMode === 'quick-edit' &&
+        isCharacterAnimationQuickEditSource(quickEditSourceLayer)
+      ) {
+        const animationResolution = '480p' as const;
+        const animationDurationSeconds = 4 as const;
+        const animationFrameCount = 32 as const;
+        const generationInputs = buildCharacterAnimationGenerationInputs(
+          normalizedPrompt,
+          quickEditSourceLayer,
+        );
+        const generated = await generateEditorCharacterAnimation({
+          sourceLayerId: quickEditSourceLayer.id,
+          sourceImageSrc: resolveCharacterAnimationSourceImageSrc(
+            quickEditSourceLayer,
+          ),
+          sourceWidth: quickEditSourceLayer.originalWidth,
+          sourceHeight: quickEditSourceLayer.originalHeight,
+          promptText: normalizedPrompt,
+          resolution: animationResolution,
+          ratio: 'same',
+          frameCount: animationFrameCount,
+          durationSeconds: animationDurationSeconds,
+          priceMudPoints: calculateCharacterAnimationPrice(
+            CHARACTER_ANIMATION_MODEL,
+            animationResolution,
+            animationDurationSeconds,
+          ),
+          model: CHARACTER_ANIMATION_MODEL,
+        });
+        addCharacterAnimationResultLayer(
+          generated,
+          `${quickEditSourceLayer.title} 快速编辑`,
+          generationInputs,
+          quickEditFrame,
+          quickEditDialogId,
+          {
+            sourceLayer: quickEditSourceLayer,
+          },
+        );
+        return;
+      }
+      if (panelMode === 'quick-edit' && isVideoQuickEditSource(quickEditSourceLayer)) {
+        const videoModel = DEFAULT_VIDEO_MODEL;
+        const videoResolution = '480p' as const;
+        const videoDurationSeconds = 4 as const;
+        const sourceVideoSrc =
+          quickEditSourceLayer.objectKey?.trim() || quickEditSourceLayer.src;
+        const generationInputs = buildVideoGenerationInputs(
+          normalizedPrompt,
+          quickEditReferences,
+        );
+        const generated = await generateEditorVideo({
+          prompt: normalizedPrompt,
+          model: videoModel,
+          aspectRatio: '16:9',
+          durationSeconds: videoDurationSeconds,
+          resolution: videoResolution,
+          mode: 'std',
+          sound: 'off',
+          priceMudPoints: calculateEditorVideoPrice(
+            videoModel,
+            videoResolution,
+            videoDurationSeconds,
+          ),
+          ...(extraReferenceImageSrcs.length
+            ? { referenceImageSrcs: extraReferenceImageSrcs }
+            : {}),
+          referenceVideoSrcs: [sourceVideoSrc],
+        });
+        addVideoResultLayer(
+          generated,
+          `${quickEditSourceLayer.title} 快速编辑`,
+          generationInputs,
+          quickEditFrame,
+          quickEditDialogId,
+          {
+            sourceLayer: quickEditSourceLayer,
+            assetKind: quickEditSourceLayer.assetKind,
+          },
+        );
+        return;
+      }
+      const sourceReferenceImageSrc = await resolveEditorImageReferenceDataUrl(
+        quickEditSourceLayer.objectKey?.trim() || quickEditSourceLayer.src,
+      );
+      const generationInputs =
+        panelMode === 'redraw'
+          ? buildEditGenerationInputs(
+              '重绘提示词',
+              normalizedPrompt,
+              quickEditSourceLayer,
+            )
+          : buildQuickEditGenerationInputs(
+              '快速编辑提示词',
+              normalizedPrompt,
+              quickEditSourceLayer,
+              quickEditReferences,
+            );
+      const isCharacterRedraw =
+        panelMode === 'redraw' && quickEditSourceLayer.assetKind === 'character';
+      const generated = await generateEditorImage({
+        prompt: normalizedPrompt,
+        size: quickEditSize,
+        aspectRatio: quickEditAspectRatio,
+        imageSize: quickEditImageSize,
+        kind: isCharacterRedraw ? 'character' : 'quick-edit',
+        model: normalizeEditorImageModel(quickEditPanel.model),
+        referenceImageSrcs: [
+          ...extraReferenceImageSrcs,
+          sourceReferenceImageSrc,
+        ],
+        projectId,
+        assetKind: quickEditSourceLayer.assetKind,
+        generationInputs,
+        assetFolderId,
+        assetLabel: `${quickEditSourceLayer.title} ${
+          panelMode === 'redraw' ? '重绘' : '快速编辑'
+        }`,
+        sourceResourceId: quickEditSourceLayer.resourceId,
+      });
+      addQuickEditResultLayer(
+        generated,
+        quickEditSourceLayer,
+        generationInputs,
+        panelMode,
+        quickEditDialogId
+          ? {
+              frame: quickEditFrame,
+              dialogId: quickEditDialogId,
+            }
+          : {},
+      );
+    } catch (error) {
+      if (quickEditDialogId) {
+        updateCanvasGenerationDialogById(quickEditDialogId, (currentDialog) => ({
+          ...currentDialog,
+          prompt: normalizedPrompt,
+          status: 'failed',
+          composerOpen: false,
+          errorMessage: resolveImageGenerationErrorMessage(error),
+        }));
+      }
+      setQuickEditPanel({
+        ...quickEditPanel,
+        aspectRatio: quickEditAspectRatio,
+        imageSize: quickEditImageSize,
+        size: quickEditSize,
+        prompt: normalizedPrompt,
+        status: 'failed',
+        errorMessage: resolveImageGenerationErrorMessage(error),
+      });
+    }
+  }, [
+    addCharacterAnimationResultLayer,
+    addQuickEditResultLayer,
+    addVideoResultLayer,
+    getGeneratingDialogPlaceholder,
+    openCanvasGenerationDialog,
+    projectId,
+    assetFolderId,
+    quickEditPanel,
+    quickEditSourceLayer,
+    selectSingleLayer,
+    setQuickEditPanel,
+    updateCanvasGenerationDialogById,
+  ]);
+
+  const submitImageGeneration = useCallback(
+    async (dialog: GenerateDialogState) => {
+      const normalizedPrompt =
+        dialog.prompt.trim() ||
+        (dialog.mode === 'edit'
+          ? '修改当前图片'
+          : dialog.mode === 'audio-sound-effect'
+            ? '游戏音效'
+            : dialog.mode === 'audio-background-music'
+              ? '游戏背景音乐'
+              : 'AI 生成图片');
+      const canvasDialog = isCanvasGenerationDialog(dialog) ? dialog : null;
+      if (canvasDialog) {
+        updateCanvasGenerationDialogById(canvasDialog.id, (currentDialog) => ({
+          ...currentDialog,
+          prompt: normalizedPrompt,
+          status: 'generating',
+          composerOpen: false,
+        }));
+      } else {
+        setGenerateDialog({
+          ...dialog,
+          prompt: normalizedPrompt,
+          status: 'generating',
+          composerOpen: dialog.mode === 'edit',
+        });
+      }
+
+      try {
+        const submissionPlan = buildImageGenerationSubmissionPlan({
+          dialog,
+          layers,
+          nextGeneratedIndex: layerCounterRef.current + 1,
+        });
+        if (submissionPlan.kind === 'edit') {
+          const referenceImageSrc = await resolveEditorImageReferenceDataUrl(
+            submissionPlan.sourceLayer.objectKey?.trim() ||
+              submissionPlan.sourceLayer.src,
+          );
+          const generated = await editEditorImage({
+            prompt: submissionPlan.normalizedPrompt,
+            sourceImageSrc: referenceImageSrc,
+            projectId,
+            assetKind: submissionPlan.sourceLayer.assetKind,
+            generationInputs: submissionPlan.generationInputs,
+            assetFolderId,
+            assetLabel: `${submissionPlan.sourceLayer.title} 修改结果`,
+            sourceResourceId: submissionPlan.sourceLayer.resourceId,
+          });
+          addGeneratedResultLayer(generated, {
+            sourceLayer: submissionPlan.sourceLayer,
+            generationInputs: submissionPlan.generationInputs,
+          });
+        } else if (submissionPlan.kind === 'video') {
+          const generated = await generateEditorVideo(submissionPlan.input);
+          addVideoResultLayer(
+            generated,
+            submissionPlan.result.title,
+            submissionPlan.result.generationInputs,
+            getGeneratingDialogPlaceholder(dialog),
+            canvasDialog?.id,
+          );
+        } else if (submissionPlan.kind === 'audio') {
+          const generated =
+            submissionPlan.audioKind === 'sound-effect'
+              ? await generateEditorSoundEffect(submissionPlan.input)
+              : await generateEditorBackgroundMusic(submissionPlan.input);
+          addAudioResultLayer(
+            generated,
+            submissionPlan.result.title,
+            submissionPlan.result.generationInputs,
+            getGeneratingDialogPlaceholder(dialog),
+            canvasDialog?.id,
+          );
+        } else {
+          const imageGenerationInput =
+            submissionPlan.input.kind === 'publication-material'
+              ? await normalizePublicationReferenceImages(submissionPlan.input)
+              : submissionPlan.input;
+          const resultTitle =
+            submissionPlan.result.title ??
+            `生成图片 ${layerCounterRef.current + 1}`;
+          const canvasCompletionPlaceholder =
+            getGeneratingDialogPlaceholder(dialog);
+          const generated = await generateEditorImage({
+            ...imageGenerationInput,
+            projectId,
+            assetKind: submissionPlan.result.assetKind,
+            generationInputs: submissionPlan.result.generationInputs,
+            assetFolderId,
+            assetLabel: resultTitle,
+            ...(canvasDialog && projectId && canvasCompletionPlaceholder
+              ? {
+                  canvasCompletion: {
+                    dialogId: canvasDialog.id,
+                    title: resultTitle,
+                    placeholder: canvasCompletionPlaceholder,
+                  },
+                }
+              : {}),
+          });
+          if (submissionPlan.rememberImageModel) {
+            rememberImageModel(submissionPlan.rememberImageModel);
+          }
+          if (generated.project && applyProjectSnapshot) {
+            applyProjectSnapshot(generated.project);
+            if (generated.asset) {
+              upsertGeneratedAsset?.(generated.asset);
+            }
+            return;
+          }
+          if (canvasDialog && projectId) {
+            updateCanvasGenerationDialogById(canvasDialog.id, (currentDialog) =>
+              currentDialog.generatedLayerId
+                ? currentDialog
+                : {
+                    ...currentDialog,
+                    status: 'idle',
+                    composerOpen: true,
+                    errorMessage: undefined,
+                  },
+            );
+            return;
+          }
+          addGeneratedResultLayer(generated, {
+            frame: canvasCompletionPlaceholder,
+            assetKind: submissionPlan.result.assetKind,
+            title: resultTitle,
+            dialogId: canvasDialog?.id,
+            generationInputs: submissionPlan.result.generationInputs,
+          });
+        }
+      } catch (error) {
+        if (canvasDialog) {
+          updateCanvasGenerationDialogById(canvasDialog.id, () => ({
+            ...canvasDialog,
+            prompt: normalizedPrompt,
+            status: 'failed',
+            composerOpen: true,
+            errorMessage: resolveImageGenerationErrorMessage(error),
+          }));
+        } else {
+          setGenerateDialog({
+            ...dialog,
+            prompt: normalizedPrompt,
+            status: 'failed',
+            composerOpen: true,
+            errorMessage: resolveImageGenerationErrorMessage(error),
+          });
+        }
+      }
+    },
+    [
+      addGeneratedResultLayer,
+      addAudioResultLayer,
+      addVideoResultLayer,
+      getGeneratingDialogPlaceholder,
+      layerCounterRef,
+      layers,
+      rememberImageModel,
+      projectId,
+      assetFolderId,
+      applyProjectSnapshot,
+      setGenerateDialog,
+      updateCanvasGenerationDialogById,
+      upsertGeneratedAsset,
+      viewport,
+    ],
+  );
+
+  const submitCharacterAnimation = useCallback(async () => {
+    if (!characterAnimationPanel || !characterAnimationSourceLayer) {
+      return;
+    }
+    const submissionPlan = buildCharacterAnimationSubmissionPlan({
+      panel: characterAnimationPanel,
+      sourceLayer: characterAnimationSourceLayer,
+    });
+    const canvasDialog = characterAnimationDialog;
+    if (canvasDialog?.mode === 'character-animation') {
+      updateCanvasGenerationDialogById(canvasDialog.id, (currentDialog) => ({
+        ...currentDialog,
+        prompt: submissionPlan.promptText,
+        characterAnimationResolution: characterAnimationPanel.resolution,
+        characterAnimationRatio: characterAnimationPanel.ratio,
+        characterAnimationFrameCount: characterAnimationPanel.frameCount,
+        characterAnimationDurationSeconds:
+          characterAnimationPanel.durationSeconds,
+        characterAnimationResult: undefined,
+        status: 'generating',
+        composerOpen: false,
+        errorMessage: undefined,
+      }));
+    }
+    const nextPanel = {
+      ...characterAnimationPanel,
+      promptText: submissionPlan.promptText,
+      status: 'generating' as const,
+      errorMessage: undefined,
+      result: undefined,
+    };
+    if (!canvasDialog) {
+      setCharacterAnimationPanel(nextPanel);
+    }
+
+    try {
+      const result = await generateEditorCharacterAnimation(
+        submissionPlan.input,
+      );
+      if (canvasDialog) {
+        addCharacterAnimationResultLayer(
+          result,
+          '角色动作',
+          buildCharacterAnimationGenerationInputs(
+            submissionPlan.promptText,
+            characterAnimationSourceLayer,
+          ),
+          getGeneratingDialogPlaceholder(canvasDialog),
+          canvasDialog.id,
+          {
+            sourceLayer: characterAnimationSourceLayer,
+          },
+        );
+        return;
+      }
+      setCharacterAnimationPanel((currentPanel) =>
+        currentPanel
+          ? {
+              ...currentPanel,
+              status: 'completed',
+              result,
+            }
+          : currentPanel,
+      );
+    } catch (error) {
+      if (canvasDialog) {
+        updateCanvasGenerationDialogById(canvasDialog.id, (currentDialog) => ({
+          ...currentDialog,
+          prompt: submissionPlan.promptText,
+          characterAnimationResolution: characterAnimationPanel.resolution,
+          characterAnimationRatio: characterAnimationPanel.ratio,
+          characterAnimationFrameCount: characterAnimationPanel.frameCount,
+          characterAnimationDurationSeconds:
+            characterAnimationPanel.durationSeconds,
+          status: 'failed',
+          composerOpen: true,
+          errorMessage:
+            error instanceof Error && error.message.trim()
+              ? error.message
+              : '生成角色动画失败',
+        }));
+        return;
+      }
+      setCharacterAnimationPanel((currentPanel) =>
+        currentPanel
+          ? {
+              ...currentPanel,
+              status: 'failed',
+              errorMessage:
+                error instanceof Error && error.message.trim()
+                  ? error.message
+                  : '生成角色动画失败',
+            }
+          : currentPanel,
+      );
+    }
+  }, [
+    addCharacterAnimationResultLayer,
+    characterAnimationDialog,
+    characterAnimationPanel,
+    characterAnimationSourceLayer,
+    getGeneratingDialogPlaceholder,
+    setCharacterAnimationPanel,
+    updateCanvasGenerationDialogById,
+  ]);
+
+  return useMemo(
+    () => ({
+      submitIconSpritesheetGeneration,
+      extractUiDesignAssets,
+      submitQuickEdit,
+      submitImageGeneration,
+      submitCharacterAnimation,
+    }),
+    [
+      submitCharacterAnimation,
+      extractUiDesignAssets,
+      submitIconSpritesheetGeneration,
+      submitImageGeneration,
+      submitQuickEdit,
+    ],
+  );
+}
diff --git a/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx b/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx
new file mode 100644
index 000000000..e1b70d30e
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationSurface.test.tsx
@@ -0,0 +1,335 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen, within } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  ImageContextMenuState,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
+import { useImageCanvasGenerationSurface } from './useImageCanvasGenerationSurface';
+
+vi.mock('../../services/image-editor/editorImageReference', () => ({
+  resolveEditorImageReferenceDataUrl: vi.fn(async (src: string) => src),
+}));
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: vi.fn(),
+    generateEditorCharacterAnimation: vi.fn(),
+    generateEditorIconSpritesheet: vi.fn(),
+    generateEditorImage: vi.fn(),
+  };
+});
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 80,
+    y: 90,
+    width: 240,
+    height: 180,
+    originalWidth: 240,
+    originalHeight: 180,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function GenerationSurfaceHarness() {
+  const [layers, setLayers] = useState<CanvasLayer[]>([createLayer()]);
+  const [activeTool, setActiveTool] = useState<CanvasTool>('select');
+  const [activeSidebarPanel, setActiveSidebarPanel] =
+    useState<SidebarPanel | null>('assets');
+  const [, setMetadataLayer] = useState<CanvasLayer | null>(null);
+  const [, setImageContextMenu] = useState<ImageContextMenuState | null>(null);
+  const layerCounterRef = useRef(0);
+  const specToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const musicToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const publicationToolWrapRef = useRef<HTMLSpanElement | null>(null);
+  const characterSpecButtonRef = useRef<HTMLButtonElement | null>(null);
+  const characterReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const iconSpecButtonRef = useRef<HTMLButtonElement | null>(null);
+  const generationReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const publicationReferenceButtonRef = useRef<HTMLButtonElement | null>(null);
+  const [viewport, setViewport] = useState({ x: 10, y: 20, scale: 2 });
+  const dialogs = useCanvasGenerationDialogs();
+  const activeDialog = dialogs.generateDialog;
+  const activeCanvasDialog =
+    activeDialog && 'id' in activeDialog
+      ? (activeDialog as CanvasGenerationDialogState)
+      : null;
+  const surface = useImageCanvasGenerationSurface({
+    layers,
+    canvasSize: { width: 900, height: 640 },
+    viewport,
+    setViewport,
+    setLayers,
+    layerCounterRef,
+    specToolWrapRef,
+    musicToolWrapRef,
+    publicationToolWrapRef,
+    characterSpecButtonRef,
+    characterReferenceButtonRef,
+    iconSpecButtonRef,
+    generationReferenceButtonRef,
+    publicationReferenceButtonRef,
+    generateDialog: dialogs.generateDialog,
+    setGenerateDialog: dialogs.setGenerateDialog,
+    activeCanvasGenerationDialog: activeCanvasDialog,
+    canvasGenerationDialogs: dialogs.canvasGenerationDialogs,
+    openCanvasGenerationDialog: dialogs.openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById: dialogs.updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById: dialogs.hasCanvasGenerationDialogById,
+    archiveActiveCanvasGenerationDialog:
+      dialogs.archiveActiveCanvasGenerationDialog,
+    removeCanvasGenerationDialogsByLayerId:
+      dialogs.removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder: dialogs.getGeneratingDialogPlaceholder,
+    appendCanvasLayersWithResources: (nextLayers) =>
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]),
+    selectSingleLayer: () => {},
+    fitLayers: () => {},
+    captureCanvasHistory: () => {},
+    setActiveTool,
+    setActiveSidebarPanel,
+    setMetadataLayer,
+    setImageContextMenu,
+    requestUpload: () => {},
+  });
+
+  return (
+    <div>
+      <span ref={specToolWrapRef}>规范入口</span>
+      <span
+        ref={musicToolWrapRef}
+        onPointerEnter={() => surface.openToolbarOptionMenu('music')}
+        onPointerLeave={() => surface.closeToolbarOptionMenu('music')}
+      >
+        音乐入口
+      </span>
+      <span ref={publicationToolWrapRef}>宣发入口</span>
+      <span data-testid="tool">{activeTool}</span>
+      <span data-testid="sidebar">{activeSidebarPanel ?? '-'}</span>
+      <span data-testid="dialog">
+        {activeDialog
+          ? `${activeDialog.mode}:${activeDialog.composerOpen !== false ? 'open' : 'closed'}:${activeDialog.placeholder ? 'placeholder' : '-'}`
+          : '-'}
+      </span>
+      <span data-testid="composer-left">
+        {surface.generationComposerStyle?.left ?? '-'}
+      </span>
+      <span data-testid="composer-top">
+        {surface.generationComposerStyle?.top ?? '-'}
+      </span>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('generate')}
+      >
+        切换生成
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('video')}
+      >
+        切换视频
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('music')}
+      >
+        切换音乐
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('spec')}
+      >
+        切换规范
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('character')}
+      >
+        切换角色
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('icon')}
+      >
+        切换图标
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('ui-design')}
+      >
+        切换UI设计
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('publication')}
+      >
+        切换宣发素材
+      </button>
+      <button
+        type="button"
+        onClick={() => surface.switchGenerationTool('select')}
+      >
+        切换选择
+      </button>
+      {surface.generationComposerNode}
+    </div>
+  );
+}
+
+describe('useImageCanvasGenerationSurface', () => {
+  it('switches generation tools while leaving non-generation tools untouched', () => {
+    render(<GenerationSurfaceHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '切换选择' }));
+    expect(screen.getByTestId('tool').textContent).toBe('select');
+
+    fireEvent.click(screen.getByRole('button', { name: '切换生成' }));
+    expect(screen.getByTestId('tool').textContent).toBe('generate');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:open:placeholder',
+    );
+    expect(screen.getByRole('dialog', { name: '生成图片' })).toBeTruthy();
+  });
+
+  it('derives composer position without rendering a standalone close button', () => {
+    render(<GenerationSurfaceHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '切换生成' }));
+    expect(screen.getByTestId('composer-left').textContent).toBe('450');
+    expect(screen.getByTestId('composer-top').textContent).toBe('1354');
+    expect(
+      screen.queryByRole('button', { name: '关闭生成图片' }),
+    ).toBeNull();
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:open:placeholder',
+    );
+  });
+
+  it('opens the spec menu through the generation surface', () => {
+    render(<GenerationSurfaceHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '切换规范' }));
+    expect(screen.getByTestId('tool').textContent).toBe('spec');
+    const menu = screen.getByRole('menu', { name: '生成规范类型' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '角色规范' }),
+    ).toBeTruthy();
+  });
+
+  it('anchors the music menu to the music tool and closes after hover leaves', () => {
+    vi.useFakeTimers();
+    try {
+      render(<GenerationSurfaceHarness />);
+      const musicAnchor = screen.getByText('音乐入口');
+      Object.defineProperty(musicAnchor, 'getBoundingClientRect', {
+        configurable: true,
+        value: () => ({
+          x: 220,
+          y: 360,
+          left: 220,
+          top: 360,
+          right: 256,
+          bottom: 396,
+          width: 36,
+          height: 36,
+          toJSON: () => ({}),
+        }),
+      });
+
+      fireEvent.pointerEnter(musicAnchor);
+
+      const menu = screen.getByRole('menu', { name: '生成音乐类型' });
+      expect(menu.style.left).toBe('220px');
+      expect(menu.style.top).toBe('360px');
+      expect(menu.style.transform).toBe('translateY(calc(-100% - 0.45rem))');
+      expect(menu.getAttribute('style') ?? '').not.toContain('left: 50%');
+
+      fireEvent.pointerLeave(musicAnchor);
+      fireEvent.pointerEnter(menu);
+      act(() => {
+        vi.advanceTimersByTime(200);
+      });
+      expect(screen.getByRole('menu', { name: '生成音乐类型' })).toBeTruthy();
+
+      fireEvent.pointerLeave(menu);
+      act(() => {
+        vi.advanceTimersByTime(200);
+      });
+      expect(screen.queryByRole('menu', { name: '生成音乐类型' })).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('opens video and UI design generation dialogs through the generation surface', () => {
+    render(<GenerationSurfaceHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '切换视频' }));
+    expect(screen.getByTestId('tool').textContent).toBe('video');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'video:open:placeholder',
+    );
+    expect(screen.getByRole('dialog', { name: '生成视频' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '切换UI设计' }));
+    expect(screen.getByTestId('tool').textContent).toBe('ui-design');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'ui-design:open:placeholder',
+    );
+    expect(screen.getByRole('dialog', { name: '生成UI设计图' })).toBeTruthy();
+  });
+
+  it('opens the music choice menu before creating audio generation dialogs', () => {
+    render(<GenerationSurfaceHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '切换音乐' }));
+
+    expect(screen.getByTestId('tool').textContent).toBe('music');
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+    const menu = screen.getByRole('menu', { name: '生成音乐类型' });
+    expect(
+      within(menu).getByRole('menuitem', { name: '生成游戏音效' }),
+    ).toBeTruthy();
+    expect(
+      within(menu).getByRole('menuitem', { name: '生成游戏背景音乐' }),
+    ).toBeTruthy();
+
+    fireEvent.click(
+      within(menu).getByRole('menuitem', { name: '生成游戏音效' }),
+    );
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'audio-sound-effect:open:placeholder',
+    );
+    expect(screen.getByRole('dialog', { name: '生成游戏音效' })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: '切换音乐' }));
+    fireEvent.click(
+      screen.getByRole('menuitem', { name: '生成游戏背景音乐' }),
+    );
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'audio-background-music:open:placeholder',
+    );
+    expect(
+      screen.getByRole('dialog', { name: '生成游戏背景音乐' }),
+    ).toBeTruthy();
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasGenerationSurface.tsx b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
new file mode 100644
index 000000000..06329c9ee
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationSurface.tsx
@@ -0,0 +1,524 @@
+import {
+  type CSSProperties,
+  type Dispatch,
+  type MutableRefObject,
+  type ReactNode,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useRef,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import type {
+  EditorAssetSnapshot,
+  EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  CanvasViewport,
+  GenerateDialogState,
+  ImageContextMenuState,
+  PublicationMaterialsWorkflowId,
+  SidebarPanel,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import { ImageCanvasGenerationComposerView } from './ImageCanvasGenerationComposerView';
+import { PUBLICATION_MATERIALS_WORKFLOWS } from './ImageCanvasPublicationMaterialsModel';
+import {
+  resolveCharacterAnimationPanelStyle,
+  resolveCropExpandPanelStyle,
+  resolveGenerationAnchor,
+  resolveGenerationComposerStyle,
+  resolveIconComposerStyle,
+  resolveQuickEditPanelStyle,
+} from './ImageCanvasOverlayModel';
+import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
+
+type CanvasGenerationDialogUpdater = (
+  dialog: CanvasGenerationDialogState,
+) => CanvasGenerationDialogState | null;
+
+type ToolbarOptionTool = Extract<CanvasTool, 'music' | 'spec' | 'publication'>;
+
+type ImageCanvasGenerationSurfaceOptions = {
+  layers: CanvasLayer[];
+  canvasSize: { width: number; height: number };
+  viewport: CanvasViewport;
+  setViewport: Dispatch<SetStateAction<CanvasViewport>>;
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  layerCounterRef: MutableRefObject<number>;
+  specToolWrapRef: RefObject<HTMLSpanElement | null>;
+  musicToolWrapRef: RefObject<HTMLSpanElement | null>;
+  publicationToolWrapRef: RefObject<HTMLSpanElement | null>;
+  characterSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  characterReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  iconSpecButtonRef: RefObject<HTMLButtonElement | null>;
+  generationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  publicationReferenceButtonRef: RefObject<HTMLButtonElement | null>;
+  generateDialog: GenerateDialogState | null;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  activeCanvasGenerationDialog: CanvasGenerationDialogState | null;
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  openCanvasGenerationDialog: (
+    dialog: Omit<CanvasGenerationDialogState, 'id'>,
+  ) => string;
+  updateCanvasGenerationDialogById: (
+    dialogId: string,
+    updater: CanvasGenerationDialogUpdater,
+  ) => void;
+  hasCanvasGenerationDialogById: (dialogId: string) => boolean;
+  archiveActiveCanvasGenerationDialog: () => void;
+  removeCanvasGenerationDialogsByLayerId: (targetLayerId: string) => void;
+  getGeneratingDialogPlaceholder: (
+    dialog: GenerateDialogState,
+  ) => GenerateDialogState['placeholder'];
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  fitLayers: (targetLayers?: CanvasLayer[]) => void;
+  captureCanvasHistory: () => void;
+  setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
+  setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
+  setMetadataLayer: Dispatch<SetStateAction<CanvasLayer | null>>;
+  setImageContextMenu: Dispatch<SetStateAction<ImageContextMenuState | null>>;
+  requestUpload: (target: UploadTarget) => void;
+  persistGeneratedAsset?: (layer: CanvasLayer) => void;
+  persistUpdatedLayerResource?: (layer: CanvasLayer) => void;
+  projectId?: string | null;
+  assetFolderId?: string | null;
+  upsertGeneratedAsset?: (asset: EditorAssetSnapshot) => void;
+  applyProjectSnapshot?: (project: EditorProjectSnapshot) => void;
+};
+
+function renderEditorPortal(node: ReactNode) {
+  if (typeof document === 'undefined') {
+    return node;
+  }
+  return createPortal(node, document.body);
+}
+
+function buildToolbarPortalMenuStyle(
+  anchor: HTMLElement | null,
+): CSSProperties {
+  const rect = anchor?.getBoundingClientRect();
+  if (!rect) {
+    return {
+      position: 'fixed',
+      left: 0,
+      top: 0,
+      right: 'auto',
+      bottom: 'auto',
+      zIndex: 70,
+    };
+  }
+
+  return {
+    position: 'fixed',
+    left: Math.round(rect.left),
+    top: Math.round(rect.top),
+    right: 'auto',
+    bottom: 'auto',
+    zIndex: 70,
+    transform: 'translateY(calc(-100% - 0.45rem))',
+  };
+}
+
+const TOOLBAR_OPTION_CLOSE_DELAY_MS = 160;
+
+export function useImageCanvasGenerationSurface({
+  layers,
+  canvasSize,
+  viewport,
+  setViewport,
+  setLayers,
+  layerCounterRef,
+  specToolWrapRef,
+  musicToolWrapRef,
+  publicationToolWrapRef,
+  characterSpecButtonRef,
+  characterReferenceButtonRef,
+  iconSpecButtonRef,
+  generationReferenceButtonRef,
+  publicationReferenceButtonRef,
+  generateDialog,
+  setGenerateDialog,
+  activeCanvasGenerationDialog,
+  canvasGenerationDialogs,
+  openCanvasGenerationDialog,
+  updateCanvasGenerationDialogById,
+  hasCanvasGenerationDialogById,
+  archiveActiveCanvasGenerationDialog,
+  removeCanvasGenerationDialogsByLayerId,
+  getGeneratingDialogPlaceholder,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+  fitLayers,
+  captureCanvasHistory,
+  setActiveTool,
+  setActiveSidebarPanel,
+  setMetadataLayer,
+  setImageContextMenu,
+  requestUpload,
+  persistGeneratedAsset,
+  persistUpdatedLayerResource,
+  projectId,
+  assetFolderId,
+  upsertGeneratedAsset,
+  applyProjectSnapshot,
+}: ImageCanvasGenerationSurfaceOptions) {
+  const toolbarOptionCloseTimerRef = useRef<ReturnType<
+    typeof setTimeout
+  > | null>(null);
+  const generationWorkflow = useImageCanvasGenerationWorkflow({
+    layers,
+    canvasSize,
+    viewport,
+    setViewport,
+    setLayers,
+    canvasGenerationDialogs,
+    layerCounterRef,
+    generateDialog,
+    setGenerateDialog,
+    openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById,
+    archiveActiveCanvasGenerationDialog,
+    removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    fitLayers,
+    captureCanvasHistory,
+    setActiveTool,
+    setActiveSidebarPanel,
+    setMetadataLayer,
+    setImageContextMenu,
+    persistGeneratedAsset,
+    persistUpdatedLayerResource,
+    projectId,
+    assetFolderId,
+    upsertGeneratedAsset,
+    applyProjectSnapshot,
+  });
+
+  const activeGenerationLayer = activeCanvasGenerationDialog?.generatedLayerId
+    ? (layers.find(
+        (layer) => layer.id === activeCanvasGenerationDialog.generatedLayerId,
+      ) ?? null)
+    : null;
+  const generationAnchor = resolveGenerationAnchor({
+    dialog: activeCanvasGenerationDialog,
+    generatedLayer: activeGenerationLayer,
+  });
+  const generationComposerStyle = resolveGenerationComposerStyle({
+    dialog: activeCanvasGenerationDialog,
+    anchor: generationAnchor,
+    viewport,
+  });
+  const iconComposerStyle = resolveIconComposerStyle({
+    dialog: activeCanvasGenerationDialog,
+    composerStyle: generationComposerStyle,
+  });
+  const quickEditPanelStyle = resolveQuickEditPanelStyle({
+    panel: generationWorkflow.quickEditPanel,
+    sourceLayer: generationWorkflow.quickEditSourceLayer,
+    viewport,
+    canvasSize,
+  });
+  const cropExpandPanelStyle = resolveCropExpandPanelStyle({
+    panel: generationWorkflow.cropExpandPanel,
+    sourceLayer: generationWorkflow.cropExpandSourceLayer,
+    viewport,
+    canvasSize,
+  });
+  const characterAnimationPanelStyle =
+    activeCanvasGenerationDialog?.mode === 'character-animation'
+      ? generationComposerStyle
+      : resolveCharacterAnimationPanelStyle({
+          panel: generationWorkflow.characterAnimationPanel,
+          sourceLayer: generationWorkflow.characterAnimationSourceLayer,
+          viewport,
+          canvasSize,
+        });
+
+  const clearToolbarOptionCloseTimer = useCallback(() => {
+    if (!toolbarOptionCloseTimerRef.current) {
+      return;
+    }
+    clearTimeout(toolbarOptionCloseTimerRef.current);
+    toolbarOptionCloseTimerRef.current = null;
+  }, []);
+
+  useEffect(
+    () => () => {
+      clearToolbarOptionCloseTimer();
+    },
+    [clearToolbarOptionCloseTimer],
+  );
+
+  const openToolbarOptionMenu = useCallback(
+    (tool: ToolbarOptionTool) => {
+      clearToolbarOptionCloseTimer();
+      generationWorkflow.setIsMusicMenuOpen(tool === 'music');
+      generationWorkflow.setIsSpecMenuOpen(tool === 'spec');
+      generationWorkflow.setIsPublicationMenuOpen(tool === 'publication');
+    },
+    [clearToolbarOptionCloseTimer, generationWorkflow],
+  );
+
+  const closeToolbarOptionMenu = useCallback(
+    (tool: ToolbarOptionTool) => {
+      clearToolbarOptionCloseTimer();
+      toolbarOptionCloseTimerRef.current = setTimeout(() => {
+        if (tool === 'music') {
+          generationWorkflow.setIsMusicMenuOpen(false);
+          return;
+        }
+        if (tool === 'publication') {
+          generationWorkflow.setIsPublicationMenuOpen(false);
+          return;
+        }
+        generationWorkflow.setIsSpecMenuOpen(false);
+      }, TOOLBAR_OPTION_CLOSE_DELAY_MS);
+    },
+    [clearToolbarOptionCloseTimer, generationWorkflow],
+  );
+
+  const switchGenerationTool = useCallback(
+    (tool: CanvasTool) => {
+      if (tool === 'generate') {
+        generationWorkflow.openGenerateDialog();
+        return true;
+      }
+      if (tool === 'video') {
+        generationWorkflow.openVideoGenerationDialog();
+        return true;
+      }
+      if (tool === 'music') {
+        openToolbarOptionMenu('music');
+        setActiveTool('music');
+        return true;
+      }
+      if (tool === 'spec') {
+        openToolbarOptionMenu('spec');
+        setActiveTool('spec');
+        return true;
+      }
+      if (tool === 'publication') {
+        openToolbarOptionMenu('publication');
+        setActiveTool('publication');
+        return true;
+      }
+      if (tool === 'character') {
+        generationWorkflow.openCharacterGenerationDialog();
+        return true;
+      }
+      if (tool === 'icon') {
+        generationWorkflow.openIconGenerationDialog();
+        return true;
+      }
+      if (tool === 'ui-design') {
+        generationWorkflow.openUiDesignGenerationDialog();
+        return true;
+      }
+      return false;
+    },
+    [generationWorkflow, openToolbarOptionMenu, setActiveTool],
+  );
+
+  const generationComposerNode = (
+    <>
+      <ImageCanvasGenerationComposerView
+        specToolWrapRef={specToolWrapRef}
+        publicationReferenceButtonRef={publicationReferenceButtonRef}
+        characterSpecButtonRef={characterSpecButtonRef}
+        characterReferenceButtonRef={characterReferenceButtonRef}
+        generationReferenceButtonRef={generationReferenceButtonRef}
+        iconSpecButtonRef={iconSpecButtonRef}
+        isPublicationReferenceMenuOpen={
+          generationWorkflow.isPublicationReferenceMenuOpen
+        }
+        isSpecMenuOpen={generationWorkflow.isSpecMenuOpen}
+        isGenerationReferenceMenuOpen={
+          generationWorkflow.isGenerationReferenceMenuOpen
+        }
+        isCharacterSpecMenuOpen={generationWorkflow.isCharacterSpecMenuOpen}
+        isCharacterReferenceMenuOpen={
+          generationWorkflow.isCharacterReferenceMenuOpen
+        }
+        isIconSpecMenuOpen={generationWorkflow.isIconSpecMenuOpen}
+        isUiDesignSpecMenuOpen={generationWorkflow.isUiDesignSpecMenuOpen}
+        isPickingPublicationReferenceFromCanvas={
+          generationWorkflow.isPickingPublicationReferenceFromCanvas
+        }
+        isPickingGenerationReferenceFromCanvas={
+          generationWorkflow.isPickingGenerationReferenceFromCanvas
+        }
+        isPickingQuickEditReferenceFromCanvas={
+          generationWorkflow.isPickingQuickEditReferenceFromCanvas
+        }
+        isPickingCharacterSpecFromCanvas={
+          generationWorkflow.isPickingCharacterSpecFromCanvas
+        }
+        isPickingCharacterReferenceFromCanvas={
+          generationWorkflow.isPickingCharacterReferenceFromCanvas
+        }
+        isPickingIconSpecFromCanvas={
+          generationWorkflow.isPickingIconSpecFromCanvas
+        }
+        isPickingUiDesignSpecFromCanvas={
+          generationWorkflow.isPickingUiDesignSpecFromCanvas
+        }
+        generateDialog={generateDialog}
+        generationComposerStyle={generationComposerStyle}
+        iconComposerStyle={iconComposerStyle}
+        quickEditPanel={generationWorkflow.quickEditPanel}
+        quickEditSourceLayer={generationWorkflow.quickEditSourceLayer}
+        quickEditPanelStyle={quickEditPanelStyle}
+        cropExpandPanel={generationWorkflow.cropExpandPanel}
+        cropExpandSourceLayer={generationWorkflow.cropExpandSourceLayer}
+        cropExpandPanelStyle={cropExpandPanelStyle}
+        characterAnimationPanel={generationWorkflow.characterAnimationPanel}
+        characterAnimationSourceLayer={
+          generationWorkflow.characterAnimationSourceLayer
+        }
+        characterAnimationPanelStyle={characterAnimationPanelStyle}
+        characterAnimationPrice={generationWorkflow.characterAnimationPrice}
+        setGenerateDialog={setGenerateDialog}
+        setQuickEditPanel={generationWorkflow.setQuickEditPanel}
+        setCropExpandPanel={generationWorkflow.setCropExpandPanel}
+        setCharacterAnimationPanel={
+          generationWorkflow.setCharacterAnimationPanel
+        }
+        setIsCharacterSpecMenuOpen={
+          generationWorkflow.setIsCharacterSpecMenuOpen
+        }
+        setIsCharacterReferenceMenuOpen={
+          generationWorkflow.setIsCharacterReferenceMenuOpen
+        }
+        setIsGenerationReferenceMenuOpen={
+          generationWorkflow.setIsGenerationReferenceMenuOpen
+        }
+        setIsPublicationReferenceMenuOpen={
+          generationWorkflow.setIsPublicationReferenceMenuOpen
+        }
+        setIsIconSpecMenuOpen={generationWorkflow.setIsIconSpecMenuOpen}
+        setIsUiDesignSpecMenuOpen={generationWorkflow.setIsUiDesignSpecMenuOpen}
+        setIsPickingGenerationReferenceFromCanvas={
+          generationWorkflow.setIsPickingGenerationReferenceFromCanvas
+        }
+        setIsPickingQuickEditReferenceFromCanvas={
+          generationWorkflow.setIsPickingQuickEditReferenceFromCanvas
+        }
+        setIsPickingPublicationReferenceFromCanvas={
+          generationWorkflow.setIsPickingPublicationReferenceFromCanvas
+        }
+        setIsPickingCharacterSpecFromCanvas={
+          generationWorkflow.setIsPickingCharacterSpecFromCanvas
+        }
+        setIsPickingCharacterReferenceFromCanvas={
+          generationWorkflow.setIsPickingCharacterReferenceFromCanvas
+        }
+        setIsPickingIconSpecFromCanvas={
+          generationWorkflow.setIsPickingIconSpecFromCanvas
+        }
+        setIsPickingUiDesignSpecFromCanvas={
+          generationWorkflow.setIsPickingUiDesignSpecFromCanvas
+        }
+        onOpenSpecDialog={generationWorkflow.openSpecDialog}
+        onRequestUpload={requestUpload}
+        onSubmitImageGeneration={(dialog) =>
+          void generationWorkflow.submitImageGeneration(dialog)
+        }
+        onSubmitIconSpritesheetGeneration={(dialog) =>
+          void generationWorkflow.submitIconSpritesheetGeneration(dialog)
+        }
+        onSubmitQuickEdit={() => void generationWorkflow.submitQuickEdit()}
+        onSubmitCropExpand={() => void generationWorkflow.submitCropExpand()}
+        onSubmitCharacterAnimation={() =>
+          void generationWorkflow.submitCharacterAnimation()
+        }
+        onUpdateSpecFormValue={generationWorkflow.updateSpecFormValue}
+        onUpdateIconDescriptionText={
+          generationWorkflow.updateIconDescriptionsText
+        }
+        onUpdateCharacterAnimationDuration={
+          generationWorkflow.updateCharacterAnimationDuration
+        }
+        onRememberImageModel={generationWorkflow.rememberImageModel}
+        onSpecMenuPointerEnter={() => openToolbarOptionMenu('spec')}
+        onSpecMenuPointerLeave={() => closeToolbarOptionMenu('spec')}
+      />
+      {generationWorkflow.isPublicationMenuOpen
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu image-canvas-editor__publication-menu"
+              label="宣发素材类型"
+              placement="top-start"
+              style={buildToolbarPortalMenuStyle(
+                publicationToolWrapRef.current,
+              )}
+              onPointerEnter={() => openToolbarOptionMenu('publication')}
+              onPointerLeave={() => closeToolbarOptionMenu('publication')}
+              onFocus={() => openToolbarOptionMenu('publication')}
+              onBlur={() => closeToolbarOptionMenu('publication')}
+            >
+              {PUBLICATION_MATERIALS_WORKFLOWS.map((workflow) => (
+                <PlatformFloatingMenuItem
+                  key={workflow.id}
+                  onClick={() =>
+                    generationWorkflow.openPublicationGenerationDialog(
+                      workflow.id as PublicationMaterialsWorkflowId,
+                    )
+                  }
+                >
+                  {workflow.label}
+                </PlatformFloatingMenuItem>
+              ))}
+            </PlatformFloatingMenu>,
+          )
+        : null}
+      {generationWorkflow.isMusicMenuOpen
+        ? renderEditorPortal(
+            <PlatformFloatingMenu
+              className="image-canvas-editor__spec-menu image-canvas-editor__portal-menu image-canvas-editor__music-menu"
+              label="生成音乐类型"
+              placement="top-start"
+              style={buildToolbarPortalMenuStyle(musicToolWrapRef.current)}
+              onPointerEnter={() => openToolbarOptionMenu('music')}
+              onPointerLeave={() => closeToolbarOptionMenu('music')}
+              onFocus={() => openToolbarOptionMenu('music')}
+              onBlur={() => closeToolbarOptionMenu('music')}
+            >
+              <PlatformFloatingMenuItem
+                onClick={generationWorkflow.openSoundEffectGenerationDialog}
+              >
+                生成游戏音效
+              </PlatformFloatingMenuItem>
+              <PlatformFloatingMenuItem
+                onClick={generationWorkflow.openBackgroundMusicGenerationDialog}
+              >
+                生成游戏背景音乐
+              </PlatformFloatingMenuItem>
+            </PlatformFloatingMenu>,
+          )
+        : null}
+    </>
+  );
+
+  return {
+    ...generationWorkflow,
+    generationComposerStyle,
+    generationComposerNode,
+    openToolbarOptionMenu,
+    closeToolbarOptionMenu,
+    switchGenerationTool,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
new file mode 100644
index 000000000..fb6ed3bf5
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx
@@ -0,0 +1,838 @@
+/* @vitest-environment jsdom */
+
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  ImageContextMenuState,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
+import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
+
+const generateEditorImageMock = vi.hoisted(() => vi.fn());
+const generateEditorCharacterAnimationMock = vi.hoisted(() => vi.fn());
+const generateEditorIconSpritesheetMock = vi.hoisted(() => vi.fn());
+const generateEditorSoundEffectMock = vi.hoisted(() => vi.fn());
+const generateEditorBackgroundMusicMock = vi.hoisted(() => vi.fn());
+const editEditorImageMock = vi.hoisted(() => vi.fn());
+const renderCropExpandImageMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorImageReference', () => ({
+  resolveEditorImageReferenceDataUrl: vi.fn(async (src: string) => src),
+}));
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    editEditorImage: editEditorImageMock,
+    generateEditorBackgroundMusic: generateEditorBackgroundMusicMock,
+    generateEditorCharacterAnimation: generateEditorCharacterAnimationMock,
+    generateEditorIconSpritesheet: generateEditorIconSpritesheetMock,
+    generateEditorImage: generateEditorImageMock,
+    generateEditorSoundEffect: generateEditorSoundEffectMock,
+  };
+});
+
+vi.mock('./ImageCanvasRasterEditModel', async () => {
+  const actual = await vi.importActual<
+    typeof import('./ImageCanvasRasterEditModel')
+  >('./ImageCanvasRasterEditModel');
+  return {
+    ...actual,
+    renderCropExpandImage: renderCropExpandImageMock,
+  };
+});
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-source',
+    resourceId: 'resource-source',
+    title: '源图',
+    src: 'data:image/png;base64,source',
+    x: 120,
+    y: 140,
+    width: 320,
+    height: 240,
+    originalWidth: 1024,
+    originalHeight: 768,
+    zIndex: 2,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function createGenerated(overrides = {}) {
+  return {
+    imageSrc: 'data:image/png;base64,generated',
+    width: 1024,
+    height: 1024,
+    sourceType: 'generated' as const,
+    prompt: '生成提示词',
+    actualPrompt: '生成提示词',
+    model: 'gpt-image-2',
+    provider: 'VectorEngine',
+    taskId: 'task-generated',
+    ...overrides,
+  };
+}
+
+function GenerationWorkflowHarness({
+  initialLayers = [createLayer()],
+  initialViewport = { x: 10, y: 20, scale: 2 },
+}: {
+  initialLayers?: CanvasLayer[];
+  initialViewport?: { x: number; y: number; scale: number };
+}) {
+  const [layers, setLayers] = useState<CanvasLayer[]>(initialLayers);
+  const [viewport, setViewport] = useState(initialViewport);
+  const [activeTool, setActiveTool] = useState<CanvasTool>('select');
+  const [activeSidebarPanel, setActiveSidebarPanel] =
+    useState<SidebarPanel | null>('assets');
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
+  const [metadataLayer, setMetadataLayer] = useState<CanvasLayer | null>(null);
+  const [imageContextMenu, setImageContextMenu] =
+    useState<ImageContextMenuState | null>({
+      layerId: 'layer-source',
+      x: 1,
+      y: 2,
+    });
+  const fitLayersMockRef = useRef(vi.fn());
+  const layerCounterRef = useRef(0);
+  const dialogs = useCanvasGenerationDialogs();
+  const workflow = useImageCanvasGenerationWorkflow({
+    layers,
+    canvasSize: { width: 900, height: 640 },
+    viewport,
+    setViewport,
+    setLayers,
+    canvasGenerationDialogs: dialogs.canvasGenerationDialogs,
+    layerCounterRef,
+    generateDialog: dialogs.generateDialog,
+    setGenerateDialog: dialogs.setGenerateDialog,
+    openCanvasGenerationDialog: dialogs.openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById: dialogs.updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById: dialogs.hasCanvasGenerationDialogById,
+    removeCanvasGenerationDialogsByLayerId:
+      dialogs.removeCanvasGenerationDialogsByLayerId,
+    getGeneratingDialogPlaceholder: dialogs.getGeneratingDialogPlaceholder,
+    archiveActiveCanvasGenerationDialog:
+      dialogs.archiveActiveCanvasGenerationDialog,
+    appendCanvasLayersWithResources: (nextLayers) =>
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]),
+    selectSingleLayer: setSelectedLayerId,
+    fitLayers: fitLayersMockRef.current,
+    captureCanvasHistory: () => {},
+    setActiveTool,
+    setActiveSidebarPanel,
+    setMetadataLayer,
+    setImageContextMenu,
+  });
+
+  const activeDialog = dialogs.generateDialog;
+  const activeCanvasDialog =
+    activeDialog && 'id' in activeDialog
+      ? (activeDialog as CanvasGenerationDialogState)
+      : null;
+
+  return (
+    <div>
+      <span data-testid="tool">{activeTool}</span>
+      <span data-testid="sidebar">{activeSidebarPanel ?? '-'}</span>
+      <span data-testid="selected">{selectedLayerId ?? '-'}</span>
+      <span data-testid="metadata">{metadataLayer?.id ?? '-'}</span>
+      <span data-testid="image-context">{imageContextMenu ? 'open' : '-'}</span>
+      <span data-testid="viewport">{`${viewport.x}:${viewport.y}:${viewport.scale}`}</span>
+      <span data-testid="placeholder">
+        {activeDialog?.placeholder
+          ? `${activeDialog.placeholder.x}:${activeDialog.placeholder.y}:${activeDialog.placeholder.width}:${activeDialog.placeholder.height}`
+          : '-'}
+      </span>
+      <span data-testid="layers">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.title}:${layer.sourceResourceId ?? '-'}:${layer.assetKind ?? '-'}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="dialog">
+        {activeDialog
+          ? `${activeDialog.mode}:${activeDialog.status}:${activeDialog.composerOpen !== false ? 'open' : 'closed'}:${activeDialog.generatedLayerId ?? '-'}:${activeDialog.placeholder ? 'placeholder' : '-'}`
+          : '-'}
+      </span>
+      <span data-testid="generation-dialogs">
+        {dialogs.canvasGenerationDialogs
+          .map(
+            (dialog) =>
+              `${dialog.id}:${dialog.mode}:${dialog.composerOpen !== false ? 'open' : 'closed'}`,
+          )
+          .join('|') || '-'}
+      </span>
+      <span data-testid="generation-references">
+        {activeDialog?.generationReferences
+          ?.map((reference) => reference.label)
+          .join('|') ?? '-'}
+      </span>
+      <span data-testid="quick-edit">
+        {workflow.quickEditPanel
+          ? `${workflow.quickEditPanel.sourceLayerId}:${workflow.quickEditPanel.status}:${workflow.quickEditPanel.prompt || '-'}`
+          : '-'}
+      </span>
+      <span data-testid="crop-expand">
+        {workflow.cropExpandPanel
+          ? `${workflow.cropExpandPanel.sourceLayerId}:${workflow.cropExpandPanel.ratio}:${workflow.cropExpandPanel.frame.x}:${workflow.cropExpandPanel.frame.y}:${workflow.cropExpandPanel.frame.width}:${workflow.cropExpandPanel.frame.height}:${workflow.cropExpandPanel.status}`
+          : '-'}
+      </span>
+      <span data-testid="character-animation">
+        {workflow.characterAnimationPanel
+          ? `${workflow.characterAnimationPanel.sourceLayerId}:${workflow.characterAnimationPanel.status}`
+          : '-'}
+      </span>
+      <span data-testid="character-animation-price">
+        {workflow.characterAnimationPrice}
+      </span>
+      <span data-testid="fit-count">
+        {fitLayersMockRef.current.mock.calls.length}
+      </span>
+      <button type="button" onClick={workflow.openGenerateDialog}>
+        打开生成
+      </button>
+      <button type="button" onClick={() => workflow.openSpecDialog('ui')}>
+        打开UI规范
+      </button>
+      <button type="button" onClick={workflow.openVideoGenerationDialog}>
+        打开视频生成
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.openRedrawPanel(
+            createLayer({
+              id: 'layer-sound',
+              title: '游戏音效',
+              src: 'data:audio/mpeg;base64,sound',
+              mediaType: 'audio',
+              assetKind: 'sound-effect',
+              width: 420,
+              height: 120,
+              originalWidth: 420,
+              originalHeight: 120,
+              prompt: '金币跳出音',
+              generationInputs: {
+                fields: [
+                  { title: 'prompt', value: '金币跳出音' },
+                  { title: 'model', value: 'audio1.0' },
+                  { title: 'duration', value: '8秒' },
+                ],
+                references: [],
+              },
+            }),
+          )
+        }
+      >
+        打开音效改造
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.setGenerateDialog({
+            mode: 'edit',
+            prompt: '',
+            status: 'idle',
+            sourceLayerId: 'layer-source',
+          })
+        }
+      >
+        打开修改状态
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.openQuickEditPanel(layers[0]!)}
+      >
+        打开快速编辑
+      </button>
+      <button type="button" onClick={() => workflow.openRedrawPanel(layers[0]!)}>
+        打开图片改造
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.openCropExpandPanel(layers[0]!)}
+      >
+        打开裁扩
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.setCropExpandPanel((currentPanel) =>
+            currentPanel
+              ? {
+                  ...currentPanel,
+                  frame: {
+                    x: currentPanel.frame.x - 10,
+                    y: currentPanel.frame.y - 20,
+                    width: currentPanel.frame.width + 60,
+                    height: currentPanel.frame.height + 40,
+                  },
+                }
+              : currentPanel,
+          )
+        }
+      >
+        拖拽裁扩边界
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.setCropExpandPanel((currentPanel) =>
+            currentPanel ? { ...currentPanel, ratio: '1:1' } : currentPanel,
+          )
+        }
+      >
+        选择1比1
+      </button>
+      <button type="button" onClick={() => void workflow.submitCropExpand()}>
+        完成裁扩
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.openCharacterAnimationPanel(
+            createLayer({ id: 'layer-character', assetKind: 'character' }),
+          )
+        }
+      >
+        打开角色动画
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.openCharacterAnimationPanel(
+            createLayer({ id: 'layer-plain' }),
+          )
+        }
+      >
+        打开普通动画
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.setGenerateDialog((currentDialog) =>
+            currentDialog
+              ? { ...currentDialog, prompt: '一张生成图' }
+              : currentDialog,
+          )
+        }
+      >
+        填写生成提示词
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (activeDialog) {
+            void workflow.submitImageGeneration(activeDialog);
+          }
+        }}
+      >
+        提交生成
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.pickGenerationReferenceFromLayer(
+            createLayer({ id: 'layer-reference', title: '画布参考图' }),
+          )
+        }
+      >
+        选择画布参考图
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          dialogs.setGenerateDialog((currentDialog) =>
+            currentDialog?.mode === 'spec'
+              ? {
+                  ...currentDialog,
+                  specReference: {
+                    id: 'spec-ref',
+                    label: '参考.png',
+                    src: 'data:image/png;base64,ref',
+                  },
+                }
+              : currentDialog,
+          )
+        }
+      >
+        添加规范参考图
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.setQuickEditPanel((currentPanel) =>
+            currentPanel
+              ? { ...currentPanel, prompt: '快速修图' }
+              : currentPanel,
+          )
+        }
+      >
+        填写快速编辑
+      </button>
+      <button type="button" onClick={() => void workflow.submitQuickEdit()}>
+        提交快速编辑
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.clearDeletedLayerGenerationState('layer-source')
+        }
+      >
+        清理源图状态
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (activeCanvasDialog) {
+            dialogs.updateCanvasGenerationDialogById(
+              activeCanvasDialog.id,
+              (dialog) => ({
+                ...dialog,
+                generatedLayerId: 'layer-source',
+              }),
+            );
+          }
+        }}
+      >
+        绑定生成图层
+      </button>
+      <button type="button" onClick={workflow.hideGeneratedLayerPanelAfterBlur}>
+        隐藏生成面板
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasGenerationWorkflow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('opens a movable canvas generation placeholder and keeps toolbar state active', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+
+    expect(screen.getByTestId('tool').textContent).toBe('generate');
+    expect(screen.getByTestId('selected').textContent).toBe('-');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:idle:open:-:placeholder',
+    );
+  });
+
+  it('calculates character animation button price from the model pricing config', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开角色动画' }));
+
+    expect(screen.getByTestId('character-animation').textContent).toBe(
+      'layer-character:idle',
+    );
+    expect(screen.getByTestId('character-animation-price').textContent).toBe(
+      '40',
+    );
+  });
+
+  it('places a new generation placeholder away from existing canvas images and centers the viewport on it', () => {
+    render(
+      <GenerationWorkflowHarness
+        initialLayers={[
+          createLayer({
+            id: 'center-layer',
+            x: 0,
+            y: -80,
+            width: 460,
+            height: 460,
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+
+    expect(screen.getByTestId('placeholder').textContent).toBe(
+      '-1056:-362:1024:1024',
+    );
+    expect(screen.getByTestId('viewport').textContent).toBe('1538:20:2');
+  });
+
+  it('places a new video generation placeholder away from existing canvas images and centers the viewport on it', () => {
+    render(
+      <GenerationWorkflowHarness
+        initialLayers={[
+          createLayer({
+            id: 'center-layer',
+            x: 0,
+            y: -80,
+            width: 460,
+            height: 460,
+          }),
+        ]}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '打开视频生成' }));
+
+    expect(screen.getByTestId('tool').textContent).toBe('video');
+    expect(screen.getByTestId('selected').textContent).toBe('-');
+    expect(screen.getByTestId('placeholder').textContent).toBe(
+      '-207:412:854:480',
+    );
+    expect(screen.getByTestId('viewport').textContent).toBe('10:-984:2');
+  });
+
+  it('opens audio remodel as an audio generation dialog next to the source layer', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开音效改造' }));
+
+    expect(screen.getByTestId('tool').textContent).toBe('music');
+    expect(screen.getByTestId('selected').textContent).toBe('layer-sound');
+    expect(screen.getByTestId('quick-edit').textContent).toBe('-');
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'audio-sound-effect:idle:open:-:placeholder',
+    );
+    expect(screen.getByTestId('placeholder').textContent).toBe(
+      '572:140:420:120',
+    );
+  });
+
+  it('keeps the active canvas generator when opening quick edit for another layer', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '打开快速编辑' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+    expect(screen.getByTestId('quick-edit').textContent).toBe(
+      'layer-source:idle:-',
+    );
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-1:generate:closed',
+    );
+  });
+
+  it('keeps the active canvas generator when opening redraw for another layer', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '打开图片改造' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+    expect(screen.getByTestId('quick-edit').textContent).toBe(
+      'layer-source:idle:-',
+    );
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-1:generate:closed',
+    );
+  });
+
+  it('submits audio remodel with restored sound parameters and appends the new audio layer', async () => {
+    generateEditorSoundEffectMock.mockResolvedValueOnce({
+      audioSrc: 'data:audio/mpeg;base64,generated',
+      width: 420,
+      height: 120,
+      sourceType: 'generated',
+      prompt: '金币跳出音',
+      actualPrompt: '金币跳出音',
+      model: 'audio1.0',
+      provider: 'VectorEngine',
+      taskId: 'task-sound',
+      priceMudPoints: 10,
+      audioKind: 'sound-effect',
+      durationSeconds: 4,
+    });
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开音效改造' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorSoundEffectMock).toHaveBeenCalledWith({
+        prompt: '金币跳出音',
+        model: 'audio1.0',
+        duration: 8,
+        priceMudPoints: 10,
+      });
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-audio-1:游戏音效 1:-:sound-effect',
+      );
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'audio-sound-effect:idle:open:layer-audio-1:placeholder',
+    );
+    expect(screen.getByTestId('placeholder').textContent).toBe(
+      '572:140:420:120',
+    );
+  });
+
+  it('submits a normal generation, appends the generated layer, and keeps the composer anchored', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '一张生成图' }),
+    );
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '填写生成提示词' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交生成' }));
+
+    expect(generateEditorImageMock).toHaveBeenCalledWith({
+      prompt: '一张生成图',
+      model: 'gemini-3.1-flash-image-preview',
+      aspectRatio: '1:1',
+      imageSize: '1K',
+      projectId: undefined,
+      assetFolderId: undefined,
+      assetKind: undefined,
+      assetLabel: '生成图片 1',
+      generationInputs: {
+        fields: [{ title: '生成提示词', value: '一张生成图' }],
+        references: [],
+      },
+    });
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:generating:closed:-:placeholder',
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-generated-1:生成图片 1',
+      );
+    });
+    expect(screen.getByTestId('sidebar').textContent).toBe('layers');
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-generated-1',
+    );
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:idle:open:layer-generated-1:placeholder',
+    );
+  });
+
+  it('adds picked canvas layers as normal generation references and submits them', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '参考生成图' }),
+    );
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择画布参考图' }));
+
+    expect(screen.getByTestId('generation-references').textContent).toBe(
+      '画布参考图',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '填写生成提示词' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith({
+        prompt: '一张生成图',
+        model: 'gemini-3.1-flash-image-preview',
+        aspectRatio: '1:1',
+        imageSize: '1K',
+        projectId: undefined,
+        assetFolderId: undefined,
+        assetKind: undefined,
+        assetLabel: '生成图片 1',
+        referenceImageSrcs: ['data:image/png;base64,source'],
+        generationInputs: {
+          fields: [{ title: '生成提示词', value: '一张生成图' }],
+          references: [
+            {
+              title: '参考图 1',
+              label: '画布参考图',
+              refType: 'project-resource',
+              refId: 'resource-source',
+            },
+          ],
+        },
+      });
+    });
+  });
+
+  it('submits spec generation with reference image and reference prompt semantics', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: 'UI规范图' }),
+    );
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开UI规范' }));
+    fireEvent.click(screen.getByRole('button', { name: '添加规范参考图' }));
+    fireEvent.click(screen.getByRole('button', { name: '提交生成' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          size: '2048x1152',
+          kind: 'spec',
+          model: 'gpt-image-2',
+          aspectRatio: '16:9',
+          imageSize: '2K',
+          referenceImageSrcs: ['data:image/png;base64,ref'],
+          prompt: expect.stringContaining('参考图生成规范'),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-generated-1:图标规范 1',
+      );
+    });
+  });
+
+  it('submits quick edits beside the source and fits source plus result', async () => {
+    generateEditorImageMock.mockResolvedValueOnce(
+      createGenerated({ prompt: '快速修图' }),
+    );
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开快速编辑' }));
+    await waitFor(() => {
+      expect(screen.getByTestId('quick-edit').textContent).toBe(
+        'layer-source:idle:-',
+      );
+    });
+    fireEvent.click(screen.getByRole('button', { name: '填写快速编辑' }));
+    await waitFor(() => {
+      expect(screen.getByTestId('quick-edit').textContent).toBe(
+        'layer-source:idle:快速修图',
+      );
+    });
+    fireEvent.click(screen.getByRole('button', { name: '提交快速编辑' }));
+
+    await waitFor(() => {
+      expect(generateEditorImageMock).toHaveBeenCalledWith({
+        prompt: '快速修图',
+        size: '1024x768',
+        aspectRatio: '4:3',
+        imageSize: '1K',
+        kind: 'quick-edit',
+        model: 'gemini-3.1-flash-image-preview',
+        referenceImageSrcs: ['data:image/png;base64,source'],
+        projectId: undefined,
+        assetFolderId: undefined,
+        assetKind: undefined,
+        assetLabel: '源图 快速编辑',
+        sourceResourceId: 'resource-source',
+        generationInputs: {
+          fields: [{ title: '快速编辑提示词', value: '快速修图' }],
+          references: [],
+        },
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-quick-edit-1:源图 快速编辑:resource-source',
+      );
+    });
+    expect(screen.getByTestId('quick-edit').textContent).toBe('-');
+    expect(screen.getByTestId('tool').textContent).toBe('select');
+    expect(screen.getByTestId('fit-count').textContent).toBe('1');
+  });
+
+  it('opens crop-expand in free ratio and completes as a new beside layer', async () => {
+    renderCropExpandImageMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,crop-expanded',
+      width: 380,
+      height: 280,
+    });
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开裁扩' }));
+    expect(screen.getByTestId('crop-expand').textContent).toBe(
+      'layer-source:free:120:140:320:240:idle',
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '拖拽裁扩边界' }));
+    fireEvent.click(screen.getByRole('button', { name: '完成裁扩' }));
+
+    await waitFor(() => {
+      expect(renderCropExpandImageMock).toHaveBeenCalledWith({
+        source: 'data:image/png;base64,source',
+        insets: {
+          left: 32,
+          top: 64,
+          right: 160,
+          bottom: 64,
+        },
+      });
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-crop-expand-1:源图 裁扩:resource-source',
+      );
+    });
+    expect(screen.getByTestId('selected').textContent).toBe(
+      'layer-crop-expand-1',
+    );
+    expect(screen.getByTestId('crop-expand').textContent).toBe('-');
+    expect(screen.getByTestId('fit-count').textContent).toBe('1');
+  });
+
+  it('clears generation side panels and linked edit dialogs when a source layer is deleted', async () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开快速编辑' }));
+    await waitFor(() => {
+      expect(screen.getByTestId('quick-edit').textContent).toBe(
+        'layer-source:idle:-',
+      );
+    });
+    fireEvent.click(screen.getByRole('button', { name: '打开修改状态' }));
+    fireEvent.click(screen.getByRole('button', { name: '清理源图状态' }));
+
+    expect(screen.getByTestId('quick-edit').textContent).toBe('-');
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+  });
+
+  it('creates a placed character action generation dialog for character layers', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开普通动画' }));
+    expect(screen.getByTestId('character-animation').textContent).toBe('-');
+    expect(screen.getByTestId('dialog').textContent).toBe('-');
+
+    fireEvent.click(screen.getByRole('button', { name: '打开角色动画' }));
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'character-animation:idle:open:-:placeholder',
+    );
+    expect(screen.getByTestId('character-animation').textContent).toBe(
+      'layer-character:idle',
+    );
+    expect(screen.getByTestId('image-context').textContent).toBe('-');
+  });
+
+  it('hides non-generating canvas generation composers without deleting placeholders', () => {
+    render(<GenerationWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '打开生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '隐藏生成面板' }));
+
+    expect(screen.getByTestId('dialog').textContent).toBe(
+      'generate:idle:closed:-:placeholder',
+    );
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasGenerationWorkflow.ts b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
new file mode 100644
index 000000000..bfc0d7678
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasGenerationWorkflow.ts
@@ -0,0 +1,1279 @@
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type PointerEvent as ReactPointerEvent,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import type {
+  EditorAssetSnapshot,
+  EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasTool,
+  CanvasViewport,
+  CharacterAnimationPanelState,
+  CropExpandPanelState,
+  CropExpandResizeHandle,
+  GenerateDialogState,
+  ImageContextMenuState,
+  PublicationMaterialsWorkflowId,
+  QuickEditPanelState,
+  SidebarPanel,
+  SpecFormValues,
+  SpecGenerationType,
+} from './ImageCanvasEditorTypes';
+import {
+  appendCharacterReference,
+  appendGenerationReference,
+  appendQuickEditReference,
+  appendPublicationReference,
+  assignCharacterSpecReference,
+  assignIconSpecReference,
+  assignUiDesignSpecReference,
+  closeGenerateComposerDialog,
+  createAudioRedrawGenerationDialogDraft,
+  createBackgroundMusicGenerationDialogDraft,
+  createCharacterAnimationGenerationDialogDraft,
+  createCharacterGenerationDialogDraft,
+  createEditDialogDraft,
+  createGenerateDialogDraft,
+  createIconGenerationDialogDraft,
+  createPublicationGenerationDialogDraft,
+  createQuickEditPanelDraft,
+  createRedrawPanelDraft,
+  createSoundEffectGenerationDialogDraft,
+  createSpecDialogDraft,
+  createUiDesignGenerationDialogDraft,
+  createVideoGenerationDialogDraft,
+  hideGeneratedLayerComposerAfterBlur,
+  updateCharacterAnimationDurationPanel,
+  updateIconDescriptionsTextInDialog,
+  updateSpecFormDialogValue,
+} from './ImageCanvasGenerationDialogModel';
+import {
+  calculateCharacterAnimationPrice,
+  CHARACTER_ANIMATION_MODEL,
+  CHARACTER_ANIMATION_DURATION_OPTIONS,
+  DEFAULT_ICON_DESCRIPTIONS,
+  DEFAULT_IMAGE_MODEL,
+  ICON_DESCRIPTION_LIMIT,
+  IMAGE_MODEL_GPT_IMAGE_2,
+  isCanvasGenerationDialog,
+} from './ImageCanvasGenerationModel';
+import {
+  centerViewportOnPlacement,
+  chooseGenerationPlacement,
+} from './ImageCanvasGenerationPlacementModel';
+import {
+  buildCropExpandInsetsFromFrame,
+  removeImageBackground,
+  renderCropExpandImage,
+} from './ImageCanvasRasterEditModel';
+import { resizeCropExpandFrame } from './ImageCanvasCropExpandModel';
+import { useImageCanvasGenerationSubmissionWorkflow } from './useImageCanvasGenerationSubmissionWorkflow';
+
+type CanvasSize = { width: number; height: number };
+
+type CropExpandResizeDragState = {
+  pointerId: number;
+  handle: CropExpandResizeHandle;
+  sourceLayerId: string;
+  startClientX: number;
+  startClientY: number;
+  startScale: number;
+  startFrame: CropExpandPanelState['frame'];
+  ratio: CropExpandPanelState['ratio'];
+};
+
+type CanvasGenerationDialogUpdater = (
+  dialog: CanvasGenerationDialogState,
+) => CanvasGenerationDialogState | null;
+
+function createCharacterAnimationPanelFromDialog(
+  dialog: CanvasGenerationDialogState | null,
+): CharacterAnimationPanelState | null {
+  if (dialog?.mode !== 'character-animation' || !dialog.sourceLayerId) {
+    return null;
+  }
+  return {
+    sourceLayerId: dialog.sourceLayerId,
+    promptText: dialog.prompt,
+    resolution: dialog.characterAnimationResolution ?? '480p',
+    ratio: dialog.characterAnimationRatio ?? 'same',
+    frameCount: dialog.characterAnimationFrameCount ?? 32,
+    durationSeconds: dialog.characterAnimationDurationSeconds ?? 4,
+    status:
+      dialog.status === 'generating'
+        ? 'generating'
+        : dialog.status === 'failed'
+          ? 'failed'
+          : dialog.characterAnimationResult
+            ? 'completed'
+            : 'idle',
+    errorMessage: dialog.errorMessage,
+    result: dialog.characterAnimationResult,
+  };
+}
+
+function applyCharacterAnimationPanelToDialog(
+  dialog: CanvasGenerationDialogState,
+  panel: CharacterAnimationPanelState | null,
+): CanvasGenerationDialogState {
+  if (dialog.mode !== 'character-animation') {
+    return dialog;
+  }
+  if (!panel) {
+    return {
+      ...dialog,
+      composerOpen: false,
+    };
+  }
+  return {
+    ...dialog,
+    prompt: panel.promptText,
+    characterAnimationResolution: panel.resolution,
+    characterAnimationRatio: panel.ratio,
+    characterAnimationFrameCount: panel.frameCount,
+    characterAnimationDurationSeconds: panel.durationSeconds,
+    characterAnimationResult: panel.result,
+    status:
+      panel.status === 'generating'
+        ? 'generating'
+        : panel.status === 'failed'
+          ? 'failed'
+          : 'idle',
+    errorMessage: panel.errorMessage,
+  };
+}
+
+type GenerationWorkflowOptions = {
+  layers: CanvasLayer[];
+  canvasSize: CanvasSize;
+  viewport: CanvasViewport;
+  setViewport: Dispatch<SetStateAction<CanvasViewport>>;
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  layerCounterRef: MutableRefObject<number>;
+  generateDialog: GenerateDialogState | null;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  openCanvasGenerationDialog: (
+    dialog: Omit<CanvasGenerationDialogState, 'id'>,
+  ) => string;
+  updateCanvasGenerationDialogById: (
+    dialogId: string,
+    updater: CanvasGenerationDialogUpdater,
+  ) => void;
+  hasCanvasGenerationDialogById: (dialogId: string) => boolean;
+  archiveActiveCanvasGenerationDialog: () => void;
+  removeCanvasGenerationDialogsByLayerId: (targetLayerId: string) => void;
+  getGeneratingDialogPlaceholder: (
+    dialog: GenerateDialogState,
+  ) => GenerateDialogState['placeholder'];
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  fitLayers: (targetLayers?: CanvasLayer[]) => void;
+  captureCanvasHistory: () => void;
+  setActiveTool: Dispatch<SetStateAction<CanvasTool>>;
+  setActiveSidebarPanel: Dispatch<SetStateAction<SidebarPanel | null>>;
+  setMetadataLayer: Dispatch<SetStateAction<CanvasLayer | null>>;
+  setImageContextMenu: Dispatch<SetStateAction<ImageContextMenuState | null>>;
+  persistGeneratedAsset?: (layer: CanvasLayer) => void;
+  persistUpdatedLayerResource?: (layer: CanvasLayer) => void;
+  projectId?: string | null;
+  assetFolderId?: string | null;
+  upsertGeneratedAsset?: (asset: EditorAssetSnapshot) => void;
+  applyProjectSnapshot?: (project: EditorProjectSnapshot) => void;
+};
+
+export function useImageCanvasGenerationWorkflow({
+  layers,
+  canvasSize,
+  viewport,
+  setViewport,
+  setLayers,
+  canvasGenerationDialogs,
+  layerCounterRef,
+  generateDialog,
+  setGenerateDialog,
+  openCanvasGenerationDialog,
+  updateCanvasGenerationDialogById,
+  hasCanvasGenerationDialogById,
+  archiveActiveCanvasGenerationDialog,
+  removeCanvasGenerationDialogsByLayerId,
+  getGeneratingDialogPlaceholder,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+  fitLayers,
+  captureCanvasHistory,
+  setActiveTool,
+  setActiveSidebarPanel,
+  setMetadataLayer,
+  setImageContextMenu,
+  persistGeneratedAsset,
+  persistUpdatedLayerResource,
+  projectId,
+  assetFolderId,
+  upsertGeneratedAsset,
+  applyProjectSnapshot,
+}: GenerationWorkflowOptions) {
+  const [isSpecMenuOpen, setIsSpecMenuOpen] = useState(false);
+  const [isGenerationReferenceMenuOpen, setIsGenerationReferenceMenuOpen] =
+    useState(false);
+  const [isCharacterSpecMenuOpen, setIsCharacterSpecMenuOpen] = useState(false);
+  const [isCharacterReferenceMenuOpen, setIsCharacterReferenceMenuOpen] =
+    useState(false);
+  const [
+    isPickingGenerationReferenceFromCanvas,
+    setIsPickingGenerationReferenceFromCanvas,
+  ] = useState(false);
+  const [
+    isPickingQuickEditReferenceFromCanvas,
+    setIsPickingQuickEditReferenceFromCanvas,
+  ] = useState(false);
+  const [
+    isPickingCharacterSpecFromCanvas,
+    setIsPickingCharacterSpecFromCanvas,
+  ] = useState(false);
+  const [
+    isPickingCharacterReferenceFromCanvas,
+    setIsPickingCharacterReferenceFromCanvas,
+  ] = useState(false);
+  const [isIconSpecMenuOpen, setIsIconSpecMenuOpen] = useState(false);
+  const [isPickingIconSpecFromCanvas, setIsPickingIconSpecFromCanvas] =
+    useState(false);
+  const [isUiDesignSpecMenuOpen, setIsUiDesignSpecMenuOpen] = useState(false);
+  const [isPickingUiDesignSpecFromCanvas, setIsPickingUiDesignSpecFromCanvas] =
+    useState(false);
+  const [isMusicMenuOpen, setIsMusicMenuOpen] = useState(false);
+  const [isPublicationMenuOpen, setIsPublicationMenuOpen] = useState(false);
+  const [isPublicationReferenceMenuOpen, setIsPublicationReferenceMenuOpen] =
+    useState(false);
+  const [
+    isPickingPublicationReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+  ] = useState(false);
+  const [quickEditPanel, setQuickEditPanel] =
+    useState<QuickEditPanelState | null>(null);
+  const [cropExpandPanel, setCropExpandPanel] =
+    useState<CropExpandPanelState | null>(null);
+  const cropExpandPanelRef = useRef<CropExpandPanelState | null>(null);
+  const cropExpandResizeDragRef = useRef<CropExpandResizeDragState | null>(
+    null,
+  );
+  const [characterAnimationPanel, setCharacterAnimationPanel] =
+    useState<CharacterAnimationPanelState | null>(null);
+  const [lastImageModel, setLastImageModel] = useState(DEFAULT_IMAGE_MODEL);
+  const characterAnimationDialog =
+    isCanvasGenerationDialog(generateDialog) &&
+    generateDialog.mode === 'character-animation'
+      ? generateDialog
+      : null;
+  const characterAnimationDialogPanel =
+    createCharacterAnimationPanelFromDialog(characterAnimationDialog);
+  const effectiveCharacterAnimationPanel =
+    characterAnimationDialogPanel ?? characterAnimationPanel;
+
+  cropExpandPanelRef.current = cropExpandPanel;
+
+  const quickEditSourceLayer = quickEditPanel
+    ? (layers.find((layer) => layer.id === quickEditPanel.sourceLayerId) ??
+      null)
+    : null;
+  const cropExpandSourceLayer = cropExpandPanel
+    ? (layers.find((layer) => layer.id === cropExpandPanel.sourceLayerId) ??
+      null)
+    : null;
+  const characterAnimationSourceLayer = effectiveCharacterAnimationPanel
+    ? (layers.find(
+        (layer) => layer.id === effectiveCharacterAnimationPanel.sourceLayerId,
+      ) ?? null)
+    : null;
+  const characterAnimationPrice = effectiveCharacterAnimationPanel
+    ? calculateCharacterAnimationPrice(
+        CHARACTER_ANIMATION_MODEL,
+        effectiveCharacterAnimationPanel.resolution,
+        effectiveCharacterAnimationPanel.durationSeconds,
+      )
+    : 0;
+  const iconDescriptionValues =
+    generateDialog?.mode === 'icon'
+      ? generateDialog.prompt.trim()
+        ? generateDialog.prompt
+            .split(/[\r\n,，、;；/|]+/u)
+            .map((description) => description.trim())
+            .filter(Boolean)
+            .slice(0, ICON_DESCRIPTION_LIMIT)
+        : (generateDialog.iconDescriptions ?? DEFAULT_ICON_DESCRIPTIONS)
+      : DEFAULT_ICON_DESCRIPTIONS;
+
+  const closeGenerationTransientState = useCallback(() => {
+    setIsSpecMenuOpen(false);
+    setIsGenerationReferenceMenuOpen(false);
+    setIsPickingQuickEditReferenceFromCanvas(false);
+    setIsCharacterSpecMenuOpen(false);
+    setIsCharacterReferenceMenuOpen(false);
+    setIsPickingGenerationReferenceFromCanvas(false);
+    setIsPickingCharacterSpecFromCanvas(false);
+    setIsPickingCharacterReferenceFromCanvas(false);
+    setIsIconSpecMenuOpen(false);
+    setIsPickingIconSpecFromCanvas(false);
+    setIsUiDesignSpecMenuOpen(false);
+    setIsPickingUiDesignSpecFromCanvas(false);
+    setIsMusicMenuOpen(false);
+    setIsPublicationMenuOpen(false);
+    setIsPublicationReferenceMenuOpen(false);
+    setIsPickingPublicationReferenceFromCanvas(false);
+    setImageContextMenu(null);
+  }, [setImageContextMenu]);
+
+  const openPlacedCanvasGenerationDialog = useCallback(
+    (draft: Omit<CanvasGenerationDialogState, 'id'>) => {
+      const draftPlaceholder = draft.placeholder;
+      if (!draftPlaceholder) {
+        openCanvasGenerationDialog(draft);
+        return;
+      }
+      // 中文注释：所有画布生成入口统一先走 placement 模型，避免新占位压住已有图层或生成占位。
+      const placement = chooseGenerationPlacement({
+        canvasSize,
+        viewport,
+        frame: draftPlaceholder,
+        layers,
+        generationDialogs: canvasGenerationDialogs,
+      });
+      openCanvasGenerationDialog({
+        ...draft,
+        placeholder: placement,
+      });
+      setViewport(
+        centerViewportOnPlacement({
+          canvasSize,
+          viewport,
+          placement,
+        }),
+      );
+    },
+    [
+      canvasGenerationDialogs,
+      canvasSize,
+      layers,
+      openCanvasGenerationDialog,
+      setViewport,
+      viewport,
+    ],
+  );
+
+  const activateCanvasGenerationEntry = useCallback(
+    (activeTool: CanvasTool) => {
+      closeGenerationTransientState();
+      setActiveTool(activeTool);
+      selectSingleLayer(null);
+      setQuickEditPanel(null);
+      setCropExpandPanel(null);
+      setCharacterAnimationPanel(null);
+    },
+    [closeGenerationTransientState, selectSingleLayer, setActiveTool],
+  );
+
+  const openGenerateDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createGenerateDialogDraft({ canvasSize, viewport }),
+    );
+    activateCanvasGenerationEntry('generate');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openSpecDialog = useCallback(
+    (specType: SpecGenerationType) => {
+      openPlacedCanvasGenerationDialog(
+        createSpecDialogDraft({ canvasSize, viewport, specType }),
+      );
+      activateCanvasGenerationEntry('generate');
+    },
+    [
+      activateCanvasGenerationEntry,
+      canvasSize,
+      openPlacedCanvasGenerationDialog,
+      viewport,
+    ],
+  );
+
+  const openCharacterAnimationPanel = useCallback(
+    (layer: CanvasLayer) => {
+      const draft = createCharacterAnimationGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        layer,
+      });
+      if (!draft) {
+        return;
+      }
+      openPlacedCanvasGenerationDialog(draft);
+      activateCanvasGenerationEntry('character');
+    },
+    [
+      activateCanvasGenerationEntry,
+      canvasSize,
+      openPlacedCanvasGenerationDialog,
+      viewport,
+    ],
+  );
+
+  const openCharacterGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createCharacterGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: lastImageModel,
+      }),
+    );
+    activateCanvasGenerationEntry('character');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    lastImageModel,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openIconGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createIconGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: lastImageModel,
+      }),
+    );
+    activateCanvasGenerationEntry('icon');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    lastImageModel,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openPublicationGenerationDialog = useCallback(
+    (workflowId: PublicationMaterialsWorkflowId) => {
+      openPlacedCanvasGenerationDialog(
+        createPublicationGenerationDialogDraft({
+          canvasSize,
+          viewport,
+          workflowId,
+        }),
+      );
+      activateCanvasGenerationEntry('publication');
+    },
+    [
+      activateCanvasGenerationEntry,
+      canvasSize,
+      openPlacedCanvasGenerationDialog,
+      viewport,
+    ],
+  );
+
+  const openVideoGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createVideoGenerationDialogDraft({ canvasSize, viewport }),
+    );
+    activateCanvasGenerationEntry('video');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openUiDesignGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createUiDesignGenerationDialogDraft({
+        canvasSize,
+        viewport,
+        imageModel: IMAGE_MODEL_GPT_IMAGE_2,
+      }),
+    );
+    activateCanvasGenerationEntry('ui-design');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openSoundEffectGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createSoundEffectGenerationDialogDraft({ canvasSize, viewport }),
+    );
+    activateCanvasGenerationEntry('music');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openBackgroundMusicGenerationDialog = useCallback(() => {
+    openPlacedCanvasGenerationDialog(
+      createBackgroundMusicGenerationDialogDraft({ canvasSize, viewport }),
+    );
+    activateCanvasGenerationEntry('music');
+  }, [
+    activateCanvasGenerationEntry,
+    canvasSize,
+    openPlacedCanvasGenerationDialog,
+    viewport,
+  ]);
+
+  const openEditDialog = useCallback(
+    (sourceLayer: CanvasLayer) => {
+      setMetadataLayer(null);
+      setImageContextMenu(null);
+      setQuickEditPanel(null);
+      setCropExpandPanel(null);
+      archiveActiveCanvasGenerationDialog();
+      setGenerateDialog(createEditDialogDraft(sourceLayer));
+      setActiveTool('generate');
+    },
+    [
+      archiveActiveCanvasGenerationDialog,
+      setActiveTool,
+      setGenerateDialog,
+      setImageContextMenu,
+      setMetadataLayer,
+    ],
+  );
+
+  const openQuickEditPanel = useCallback(
+    (sourceLayer: CanvasLayer) => {
+      setImageContextMenu(null);
+      setMetadataLayer(null);
+      archiveActiveCanvasGenerationDialog();
+      setGenerateDialog(null);
+      setCropExpandPanel(null);
+      setCharacterAnimationPanel(null);
+      setQuickEditPanel(createQuickEditPanelDraft(sourceLayer));
+      selectSingleLayer(sourceLayer.id);
+      setActiveTool('generate');
+    },
+    [
+      selectSingleLayer,
+      archiveActiveCanvasGenerationDialog,
+      setActiveTool,
+      setGenerateDialog,
+      setImageContextMenu,
+      setMetadataLayer,
+    ],
+  );
+
+  const updateSourceLayer = useCallback(
+    (
+      sourceLayerId: string,
+      updater: (layer: CanvasLayer) => CanvasLayer,
+    ) => {
+      const sourceLayer = layers.find((layer) => layer.id === sourceLayerId);
+      if (!sourceLayer) {
+        return;
+      }
+      const updatedLayer = updater(sourceLayer);
+      captureCanvasHistory();
+      setLayers((currentLayers) =>
+        currentLayers.map((layer) =>
+          layer.id === sourceLayerId ? updatedLayer : layer,
+        ),
+      );
+      persistUpdatedLayerResource?.(updatedLayer);
+      selectSingleLayer(sourceLayerId);
+      fitLayers([updatedLayer]);
+    },
+    [
+      captureCanvasHistory,
+      fitLayers,
+      layers,
+      persistUpdatedLayerResource,
+      selectSingleLayer,
+      setLayers,
+    ],
+  );
+
+  const openRedrawPanel = useCallback(
+    (sourceLayer: CanvasLayer) => {
+      setImageContextMenu(null);
+      setMetadataLayer(null);
+      setCropExpandPanel(null);
+      setCharacterAnimationPanel(null);
+      if (sourceLayer.mediaType === 'audio') {
+        const audioDraft = createAudioRedrawGenerationDialogDraft(sourceLayer);
+        if (!audioDraft) {
+          return;
+        }
+        setQuickEditPanel(null);
+        selectSingleLayer(sourceLayer.id);
+        openCanvasGenerationDialog(audioDraft);
+        setActiveTool('music');
+        return;
+      }
+      archiveActiveCanvasGenerationDialog();
+      setGenerateDialog(null);
+      setQuickEditPanel(createRedrawPanelDraft(sourceLayer));
+      selectSingleLayer(sourceLayer.id);
+      setActiveTool('generate');
+    },
+    [
+      archiveActiveCanvasGenerationDialog,
+      openCanvasGenerationDialog,
+      selectSingleLayer,
+      setActiveTool,
+      setGenerateDialog,
+      setImageContextMenu,
+      setMetadataLayer,
+    ],
+  );
+
+  const openCropExpandPanel = useCallback(
+    (sourceLayer: CanvasLayer) => {
+      setImageContextMenu(null);
+      setMetadataLayer(null);
+      archiveActiveCanvasGenerationDialog();
+      setGenerateDialog(null);
+      setQuickEditPanel(null);
+      setCharacterAnimationPanel(null);
+      setCropExpandPanel({
+        sourceLayerId: sourceLayer.id,
+        frame: {
+          x: sourceLayer.x,
+          y: sourceLayer.y,
+          width: sourceLayer.width,
+          height: sourceLayer.height,
+        },
+        ratio: 'free',
+        status: 'idle',
+      });
+      selectSingleLayer(sourceLayer.id);
+      setActiveTool('select');
+    },
+    [
+      archiveActiveCanvasGenerationDialog,
+      selectSingleLayer,
+      setActiveTool,
+      setGenerateDialog,
+      setImageContextMenu,
+      setMetadataLayer,
+    ],
+  );
+
+  const startCropExpandFrameResize = useCallback(
+    (
+      event: ReactPointerEvent<HTMLButtonElement>,
+      handle: CropExpandResizeHandle,
+    ) => {
+      const currentPanel = cropExpandPanelRef.current;
+      if (!currentPanel) {
+        return;
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      cropExpandResizeDragRef.current = {
+        pointerId: event.pointerId,
+        handle,
+        sourceLayerId: currentPanel.sourceLayerId,
+        startClientX: event.clientX,
+        startClientY: event.clientY,
+        startScale:
+          Number.isFinite(viewport.scale) && viewport.scale > 0
+            ? viewport.scale
+            : 1,
+        startFrame: currentPanel.frame,
+        ratio: currentPanel.ratio,
+      };
+      selectSingleLayer(currentPanel.sourceLayerId);
+    },
+    [selectSingleLayer, viewport.scale],
+  );
+
+  useEffect(() => {
+    const handlePointerMove = (event: PointerEvent) => {
+      const dragState = cropExpandResizeDragRef.current;
+      if (!dragState || dragState.pointerId !== event.pointerId) {
+        return;
+      }
+      event.preventDefault();
+      const deltaX =
+        (event.clientX - dragState.startClientX) / dragState.startScale;
+      const deltaY =
+        (event.clientY - dragState.startClientY) / dragState.startScale;
+      const nextFrame = resizeCropExpandFrame({
+        frame: dragState.startFrame,
+        handle: dragState.handle,
+        deltaX,
+        deltaY,
+        ratio: dragState.ratio,
+      });
+      setCropExpandPanel((currentPanel) =>
+        currentPanel?.sourceLayerId === dragState.sourceLayerId
+          ? {
+              ...currentPanel,
+              frame: nextFrame,
+              status:
+                currentPanel.status === 'failed'
+                  ? 'idle'
+                  : currentPanel.status,
+              errorMessage:
+                currentPanel.status === 'failed'
+                  ? undefined
+                  : currentPanel.errorMessage,
+            }
+          : currentPanel,
+      );
+    };
+    const handlePointerUp = (event: PointerEvent) => {
+      const dragState = cropExpandResizeDragRef.current;
+      if (!dragState || dragState.pointerId !== event.pointerId) {
+        return;
+      }
+      cropExpandResizeDragRef.current = null;
+    };
+
+    window.addEventListener('pointermove', handlePointerMove);
+    window.addEventListener('pointerup', handlePointerUp);
+    window.addEventListener('pointercancel', handlePointerUp);
+    return () => {
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', handlePointerUp);
+      window.removeEventListener('pointercancel', handlePointerUp);
+    };
+  }, [setCropExpandPanel]);
+
+  const submitCropExpand = useCallback(async () => {
+    if (!cropExpandPanel || !cropExpandSourceLayer) {
+      return;
+    }
+
+    try {
+      const insets = buildCropExpandInsetsFromFrame({
+        layer: cropExpandSourceLayer,
+        frame: cropExpandPanel.frame,
+      });
+      setCropExpandPanel({
+        ...cropExpandPanel,
+        status: 'processing',
+        errorMessage: undefined,
+      });
+      const result = await renderCropExpandImage({
+        source: cropExpandSourceLayer.src,
+        insets,
+      });
+      layerCounterRef.current += 1;
+      const cropExpandIndex = layerCounterRef.current;
+      const nextLayer: CanvasLayer = {
+        ...cropExpandSourceLayer,
+        id: `layer-crop-expand-${cropExpandIndex}`,
+        resourceId: `local-resource-crop-expand-${cropExpandIndex}`,
+        title: `${cropExpandSourceLayer.title} 裁扩`,
+        src: result.imageSrc,
+        x: cropExpandSourceLayer.x + cropExpandSourceLayer.width + 32,
+        y: cropExpandSourceLayer.y,
+        width: result.width,
+        height: result.height,
+        originalWidth: result.width,
+        originalHeight: result.height,
+        zIndex: cropExpandIndex + 10,
+        sourceType: 'generated',
+        sourceResourceId: cropExpandSourceLayer.resourceId,
+        objectKey: null,
+        assetObjectId: null,
+        sourceAssetId: null,
+      };
+      captureCanvasHistory();
+      appendCanvasLayersWithResources([nextLayer]);
+      persistGeneratedAsset?.(nextLayer);
+      selectSingleLayer(nextLayer.id);
+      fitLayers([cropExpandSourceLayer, nextLayer]);
+      setCropExpandPanel(null);
+      setActiveSidebarPanel('layers');
+    } catch (error) {
+      setCropExpandPanel({
+        ...cropExpandPanel,
+        status: 'failed',
+        errorMessage:
+          error instanceof Error && error.message.trim()
+            ? error.message
+            : '裁扩图片失败',
+      });
+    }
+  }, [
+    cropExpandPanel,
+    cropExpandSourceLayer,
+    appendCanvasLayersWithResources,
+    captureCanvasHistory,
+    fitLayers,
+    layerCounterRef,
+    persistGeneratedAsset,
+    selectSingleLayer,
+    setActiveSidebarPanel,
+  ]);
+
+  const removeSelectedLayerBackground = useCallback(
+    async (sourceLayer: CanvasLayer) => {
+      setImageContextMenu(null);
+      setMetadataLayer(null);
+      setCropExpandPanel(null);
+      setQuickEditPanel(null);
+      try {
+        const result = await removeImageBackground(sourceLayer.src);
+        updateSourceLayer(sourceLayer.id, (layer) => ({
+          ...layer,
+          src: result.imageSrc,
+          width: result.width,
+          height: result.height,
+          originalWidth: result.width,
+          originalHeight: result.height,
+          objectKey: null,
+          assetObjectId: null,
+          sourceAssetId: null,
+        }));
+        setActiveSidebarPanel('layers');
+      } catch (error) {
+        window.alert(
+          error instanceof Error && error.message.trim()
+            ? error.message
+            : '去除背景失败',
+        );
+      }
+    },
+    [
+      setActiveSidebarPanel,
+      setImageContextMenu,
+      setMetadataLayer,
+      updateSourceLayer,
+    ],
+  );
+
+  const pickCharacterSpecFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      setGenerateDialog((currentDialog) =>
+        assignCharacterSpecReference(currentDialog, layer),
+      );
+      setIsPickingCharacterSpecFromCanvas(false);
+      setIsCharacterSpecMenuOpen(false);
+      setImageContextMenu(null);
+    },
+    [setGenerateDialog, setImageContextMenu],
+  );
+
+  const pickGenerationReferenceFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      setGenerateDialog((currentDialog) =>
+        appendGenerationReference(currentDialog, layer),
+      );
+      setIsPickingGenerationReferenceFromCanvas(false);
+      setIsGenerationReferenceMenuOpen(false);
+      setImageContextMenu(null);
+    },
+    [setGenerateDialog, setImageContextMenu],
+  );
+
+  const pickQuickEditReferenceFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      setQuickEditPanel((currentPanel) =>
+        appendQuickEditReference(currentPanel, layer),
+      );
+      setIsPickingQuickEditReferenceFromCanvas(false);
+      setImageContextMenu(null);
+    },
+    [setImageContextMenu],
+  );
+
+  const pickCharacterReferenceFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      setGenerateDialog((currentDialog) =>
+        appendCharacterReference(currentDialog, layer),
+      );
+      setIsPickingCharacterReferenceFromCanvas(false);
+      setImageContextMenu(null);
+    },
+    [setGenerateDialog, setImageContextMenu],
+  );
+
+  const pickIconSpecFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      const nextDialog = assignIconSpecReference(generateDialog, layer);
+      setGenerateDialog(nextDialog);
+      if (nextDialog === generateDialog) {
+        return;
+      }
+      setIsPickingIconSpecFromCanvas(false);
+      setIsIconSpecMenuOpen(false);
+      setImageContextMenu(null);
+    },
+    [generateDialog, setGenerateDialog, setImageContextMenu],
+  );
+
+  const pickUiDesignSpecFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      const nextDialog = assignUiDesignSpecReference(generateDialog, layer);
+      setGenerateDialog(nextDialog);
+      if (nextDialog === generateDialog) {
+        return;
+      }
+      setIsPickingUiDesignSpecFromCanvas(false);
+      setIsUiDesignSpecMenuOpen(false);
+      setImageContextMenu(null);
+    },
+    [generateDialog, setGenerateDialog, setImageContextMenu],
+  );
+
+  const pickPublicationReferenceFromLayer = useCallback(
+    (layer: CanvasLayer) => {
+      setGenerateDialog((currentDialog) =>
+        appendPublicationReference(currentDialog, layer),
+      );
+      setIsPickingPublicationReferenceFromCanvas(false);
+      setIsPublicationReferenceMenuOpen(false);
+      setImageContextMenu(null);
+    },
+    [setGenerateDialog, setImageContextMenu],
+  );
+
+  const updateIconDescriptionsText = useCallback(
+    (value: string) => {
+      setGenerateDialog((currentDialog) =>
+        updateIconDescriptionsTextInDialog(currentDialog, value),
+      );
+    },
+    [setGenerateDialog],
+  );
+
+  const generationSubmissionWorkflow = useImageCanvasGenerationSubmissionWorkflow({
+    layers,
+    canvasSize,
+    viewport,
+    layerCounterRef,
+    quickEditPanel,
+    quickEditSourceLayer,
+    setQuickEditPanel,
+    characterAnimationPanel: effectiveCharacterAnimationPanel,
+    characterAnimationDialog,
+    characterAnimationSourceLayer,
+    setCharacterAnimationPanel,
+    setGenerateDialog,
+    openCanvasGenerationDialog,
+    updateCanvasGenerationDialogById,
+    hasCanvasGenerationDialogById,
+    getGeneratingDialogPlaceholder,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    fitLayers,
+    setActiveTool,
+    setActiveSidebarPanel,
+    rememberImageModel: setLastImageModel,
+    projectId,
+    assetFolderId,
+    upsertGeneratedAsset,
+    applyProjectSnapshot,
+  });
+
+  const setEffectiveCharacterAnimationPanel: Dispatch<
+    SetStateAction<CharacterAnimationPanelState | null>
+  > = useCallback(
+    (updater) => {
+      setGenerateDialog((currentDialog) => {
+        if (
+          !isCanvasGenerationDialog(currentDialog) ||
+          currentDialog.mode !== 'character-animation'
+        ) {
+          return currentDialog;
+        }
+        const currentPanel =
+          createCharacterAnimationPanelFromDialog(currentDialog);
+        const nextPanel =
+          typeof updater === 'function'
+            ? updater(currentPanel)
+            : updater;
+        return applyCharacterAnimationPanelToDialog(
+          currentDialog,
+          nextPanel,
+        );
+      });
+      setCharacterAnimationPanel((currentPanel) => {
+        if (characterAnimationDialog) {
+          return currentPanel;
+        }
+        return typeof updater === 'function'
+          ? updater(currentPanel)
+          : updater;
+      });
+    },
+    [characterAnimationDialog, setGenerateDialog],
+  );
+  const {
+    extractUiDesignAssets: submitUiDesignAssetExtraction,
+    submitCharacterAnimation,
+    submitIconSpritesheetGeneration,
+    submitImageGeneration,
+    submitQuickEdit,
+  } = generationSubmissionWorkflow;
+
+  const extractUiDesignAssets = useCallback(
+    (sourceLayer: CanvasLayer) => {
+      closeGenerationTransientState();
+      setMetadataLayer(null);
+      setQuickEditPanel(null);
+      setCropExpandPanel(null);
+      setCharacterAnimationPanel(null);
+      selectSingleLayer(sourceLayer.id);
+      setActiveTool('select');
+      void submitUiDesignAssetExtraction(sourceLayer);
+    },
+    [
+      closeGenerationTransientState,
+      selectSingleLayer,
+      setActiveTool,
+      setCharacterAnimationPanel,
+      setCropExpandPanel,
+      setMetadataLayer,
+      setQuickEditPanel,
+      submitUiDesignAssetExtraction,
+    ],
+  );
+
+  const updateSpecFormValue = useCallback(
+    (key: keyof SpecFormValues, value: string) => {
+      setGenerateDialog((currentDialog) =>
+        updateSpecFormDialogValue(currentDialog, key, value),
+      );
+    },
+    [setGenerateDialog],
+  );
+
+  const updateCharacterAnimationDuration = useCallback(
+    (frameCountValue: string) => {
+      const option = CHARACTER_ANIMATION_DURATION_OPTIONS.find(
+        (item) => String(item.frameCount) === frameCountValue,
+      );
+      if (option) {
+        setGenerateDialog((currentDialog) =>
+          currentDialog?.mode === 'character-animation'
+            ? {
+                ...currentDialog,
+                characterAnimationFrameCount: option.frameCount,
+                characterAnimationDurationSeconds: option.durationSeconds,
+                status:
+                  currentDialog.status === 'failed'
+                    ? 'idle'
+                    : currentDialog.status,
+                errorMessage:
+                  currentDialog.status === 'failed'
+                    ? undefined
+                    : currentDialog.errorMessage,
+              }
+            : currentDialog,
+        );
+      }
+      setCharacterAnimationPanel((currentPanel) =>
+        updateCharacterAnimationDurationPanel(currentPanel, frameCountValue),
+      );
+    },
+    [setGenerateDialog],
+  );
+
+  const hideGeneratedLayerPanelAfterBlur = useCallback(() => {
+    setGenerateDialog((currentDialog) =>
+      hideGeneratedLayerComposerAfterBlur(currentDialog),
+    );
+  }, [setGenerateDialog]);
+
+  const closeGenerateComposer = useCallback(() => {
+    setGenerateDialog(closeGenerateComposerDialog);
+    setActiveTool('select');
+  }, [setActiveTool, setGenerateDialog]);
+
+  const clearDeletedLayerGenerationState = useCallback(
+    (targetLayerId: string) => {
+      setQuickEditPanel((currentPanel) =>
+        currentPanel?.sourceLayerId === targetLayerId ? null : currentPanel,
+      );
+      setQuickEditPanel((currentPanel) =>
+        currentPanel
+          ? {
+              ...currentPanel,
+              quickEditReferences: (
+                currentPanel.quickEditReferences ?? []
+              ).filter((reference) => reference.id !== `canvas-${targetLayerId}`),
+            }
+          : currentPanel,
+      );
+      setCropExpandPanel((currentPanel) =>
+        currentPanel?.sourceLayerId === targetLayerId ? null : currentPanel,
+      );
+      setCharacterAnimationPanel((currentPanel) =>
+        currentPanel?.sourceLayerId === targetLayerId ? null : currentPanel,
+      );
+      setGenerateDialog((currentDialog) =>
+        currentDialog?.mode === 'edit' &&
+        currentDialog.sourceLayerId === targetLayerId
+          ? null
+          : currentDialog,
+      );
+      removeCanvasGenerationDialogsByLayerId(targetLayerId);
+    },
+    [removeCanvasGenerationDialogsByLayerId, setGenerateDialog],
+  );
+
+  return useMemo(
+    () => ({
+      quickEditPanel,
+      setQuickEditPanel,
+      quickEditSourceLayer,
+      cropExpandPanel,
+      setCropExpandPanel,
+      cropExpandSourceLayer,
+      characterAnimationPanel: effectiveCharacterAnimationPanel,
+      setCharacterAnimationPanel: setEffectiveCharacterAnimationPanel,
+      characterAnimationSourceLayer,
+      characterAnimationPrice,
+      iconDescriptionValues,
+      isSpecMenuOpen,
+      setIsSpecMenuOpen,
+      isGenerationReferenceMenuOpen,
+      setIsGenerationReferenceMenuOpen,
+      isCharacterSpecMenuOpen,
+      setIsCharacterSpecMenuOpen,
+      isCharacterReferenceMenuOpen,
+      setIsCharacterReferenceMenuOpen,
+      isPickingGenerationReferenceFromCanvas,
+      setIsPickingGenerationReferenceFromCanvas,
+      isPickingQuickEditReferenceFromCanvas,
+      setIsPickingQuickEditReferenceFromCanvas,
+      isPickingCharacterSpecFromCanvas,
+      setIsPickingCharacterSpecFromCanvas,
+      isPickingCharacterReferenceFromCanvas,
+      setIsPickingCharacterReferenceFromCanvas,
+      isIconSpecMenuOpen,
+      setIsIconSpecMenuOpen,
+      isPickingIconSpecFromCanvas,
+      setIsPickingIconSpecFromCanvas,
+      isUiDesignSpecMenuOpen,
+      setIsUiDesignSpecMenuOpen,
+      isPickingUiDesignSpecFromCanvas,
+      setIsPickingUiDesignSpecFromCanvas,
+      isMusicMenuOpen,
+      setIsMusicMenuOpen,
+      isPublicationMenuOpen,
+      setIsPublicationMenuOpen,
+      isPublicationReferenceMenuOpen,
+      setIsPublicationReferenceMenuOpen,
+      isPickingPublicationReferenceFromCanvas,
+      setIsPickingPublicationReferenceFromCanvas,
+      openGenerateDialog,
+      openSpecDialog,
+      openCharacterAnimationPanel,
+      openCharacterGenerationDialog,
+      openIconGenerationDialog,
+      openPublicationGenerationDialog,
+      openVideoGenerationDialog,
+      openUiDesignGenerationDialog,
+      openSoundEffectGenerationDialog,
+      openBackgroundMusicGenerationDialog,
+      openEditDialog,
+      openQuickEditPanel,
+      openRedrawPanel,
+      openCropExpandPanel,
+      startCropExpandFrameResize,
+      removeSelectedLayerBackground,
+      extractUiDesignAssets,
+      pickCharacterSpecFromLayer,
+      pickGenerationReferenceFromLayer,
+      pickQuickEditReferenceFromLayer,
+      pickCharacterReferenceFromLayer,
+      pickIconSpecFromLayer,
+      pickUiDesignSpecFromLayer,
+      pickPublicationReferenceFromLayer,
+      submitIconSpritesheetGeneration,
+      submitQuickEdit,
+      submitCropExpand,
+      submitImageGeneration,
+      updateSpecFormValue,
+      updateIconDescriptionsText,
+      updateCharacterAnimationDuration,
+      rememberImageModel: setLastImageModel,
+      submitCharacterAnimation,
+      hideGeneratedLayerPanelAfterBlur,
+      closeGenerateComposer,
+      clearDeletedLayerGenerationState,
+    }),
+    [
+      effectiveCharacterAnimationPanel,
+      characterAnimationPrice,
+      characterAnimationSourceLayer,
+      clearDeletedLayerGenerationState,
+      closeGenerateComposer,
+      cropExpandPanel,
+      cropExpandSourceLayer,
+      setEffectiveCharacterAnimationPanel,
+      hideGeneratedLayerPanelAfterBlur,
+      iconDescriptionValues,
+      isCharacterReferenceMenuOpen,
+      isCharacterSpecMenuOpen,
+      isIconSpecMenuOpen,
+      isGenerationReferenceMenuOpen,
+      isPickingCharacterReferenceFromCanvas,
+      isPickingCharacterSpecFromCanvas,
+      isPickingGenerationReferenceFromCanvas,
+      isPickingQuickEditReferenceFromCanvas,
+      isPickingIconSpecFromCanvas,
+      isPickingUiDesignSpecFromCanvas,
+      isUiDesignSpecMenuOpen,
+      isMusicMenuOpen,
+      isPublicationMenuOpen,
+      isPublicationReferenceMenuOpen,
+      isSpecMenuOpen,
+      isPickingPublicationReferenceFromCanvas,
+      openBackgroundMusicGenerationDialog,
+      openCharacterAnimationPanel,
+      openCharacterGenerationDialog,
+      openCropExpandPanel,
+      openEditDialog,
+      extractUiDesignAssets,
+      openGenerateDialog,
+      openIconGenerationDialog,
+      openPublicationGenerationDialog,
+      openRedrawPanel,
+      openUiDesignGenerationDialog,
+      openQuickEditPanel,
+      openSpecDialog,
+      startCropExpandFrameResize,
+      openSoundEffectGenerationDialog,
+      openVideoGenerationDialog,
+      pickCharacterReferenceFromLayer,
+      pickCharacterSpecFromLayer,
+      pickGenerationReferenceFromLayer,
+      pickQuickEditReferenceFromLayer,
+      pickIconSpecFromLayer,
+      pickPublicationReferenceFromLayer,
+      pickUiDesignSpecFromLayer,
+      quickEditPanel,
+      quickEditSourceLayer,
+      removeSelectedLayerBackground,
+      submitCharacterAnimation,
+      submitCropExpand,
+      submitIconSpritesheetGeneration,
+      submitImageGeneration,
+      submitQuickEdit,
+      updateCharacterAnimationDuration,
+      updateIconDescriptionsText,
+      updateSpecFormValue,
+    ],
+  );
+}
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
new file mode 100644
index 000000000..3249cc25b
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.test.tsx
@@ -0,0 +1,494 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasTool,
+  GenerateDialogState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasKeyboardShortcuts } from './useImageCanvasKeyboardShortcuts';
+
+function createPlaceholderDialog(
+  mode: GenerateDialogState['mode'] = 'generate',
+): GenerateDialogState {
+  return {
+    id: 'dialog-1',
+    mode,
+    prompt: '生成一张图片',
+    status: 'idle',
+    composerOpen: true,
+    placeholder: {
+      x: 10,
+      y: 20,
+      width: 320,
+      height: 240,
+      originalWidth: 320,
+      originalHeight: 240,
+    },
+  };
+}
+
+function applyGenerateDialogUpdater(
+  updater:
+    | GenerateDialogState
+    | null
+    | ((dialog: GenerateDialogState | null) => GenerateDialogState | null),
+  currentDialog: GenerateDialogState | null,
+) {
+  return typeof updater === 'function' ? updater(currentDialog) : updater;
+}
+
+function applyQuickEditPanelUpdater(
+  updater:
+    | QuickEditPanelState
+    | null
+    | ((panel: QuickEditPanelState | null) => QuickEditPanelState | null),
+  currentPanel: QuickEditPanelState | null,
+) {
+  return typeof updater === 'function' ? updater(currentPanel) : updater;
+}
+
+function KeyboardShortcutsHarness({
+  selectedLayerId = null,
+  selectedLayerIds = selectedLayerId ? [selectedLayerId] : [],
+  initialGenerateDialog = null,
+  initialQuickEditPanel = null,
+  initialTool = 'select',
+  undoCanvasChange = vi.fn(),
+  redoCanvasChange = vi.fn(),
+  deleteLayerById = vi.fn(),
+  deleteSelectedCanvasObjects = vi.fn(),
+  requestRemoveCanvasGenerationDialog = vi.fn(),
+  closeEditorChromePanels = vi.fn(),
+}: {
+  selectedLayerId?: string | null;
+  selectedLayerIds?: string[];
+  initialGenerateDialog?: GenerateDialogState | null;
+  initialQuickEditPanel?: QuickEditPanelState | null;
+  initialTool?: CanvasTool;
+  undoCanvasChange?: () => void;
+  redoCanvasChange?: () => void;
+  deleteLayerById?: (layerId: string | null) => void;
+  deleteSelectedCanvasObjects?: () => void;
+  requestRemoveCanvasGenerationDialog?: (
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  closeEditorChromePanels?: () => void;
+}) {
+  const [activeTool, setActiveTool] = useState<CanvasTool>(initialTool);
+  const [generateDialog, setGenerateDialogState] =
+    useState<GenerateDialogState | null>(initialGenerateDialog);
+  const [quickEditPanel, setQuickEditPanelState] =
+    useState<QuickEditPanelState | null>(initialQuickEditPanel);
+  const [imageContextMenuOpen, setImageContextMenuOpen] = useState(true);
+  const [contextMenuOpen, setContextMenuOpen] = useState(true);
+  const [isSpecMenuOpen, setIsSpecMenuOpen] = useState(true);
+  const [, setIsGenerationReferenceMenuOpen] = useState(true);
+  const [isPublicationReferenceMenuOpen, setIsPublicationReferenceMenuOpen] =
+    useState(true);
+  const [, setIsPickingGenerationReferenceFromCanvas] = useState(true);
+  const [, setIsPickingQuickEditReferenceFromCanvas] = useState(true);
+  const [
+    isPickingPublicationReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+  ] = useState(true);
+  const [isCharacterSpecMenuOpen, setIsCharacterSpecMenuOpen] = useState(true);
+  const [isCharacterReferenceMenuOpen, setIsCharacterReferenceMenuOpen] =
+    useState(true);
+  const [isPickingCharacterSpecFromCanvas, setIsPickingCharacterSpecFromCanvas] =
+    useState(true);
+  const [
+    isPickingCharacterReferenceFromCanvas,
+    setIsPickingCharacterReferenceFromCanvas,
+  ] = useState(true);
+  const [isIconSpecMenuOpen, setIsIconSpecMenuOpen] = useState(true);
+  const [isPickingIconSpecFromCanvas, setIsPickingIconSpecFromCanvas] =
+    useState(true);
+  const [, setIsUiDesignSpecMenuOpen] = useState(true);
+  const [, setIsPickingUiDesignSpecFromCanvas] =
+    useState(true);
+  const [isSpacePanning, setIsSpacePanning] = useState(false);
+  const [shiftPressed, setShiftPressed] = useState(false);
+  const generateDialogRef = useRef<GenerateDialogState | null>(generateDialog);
+  const selectedLayerIdRef = useRef<string | null>(selectedLayerId);
+  const selectedLayerIdsRef = useRef<string[]>(selectedLayerIds);
+  generateDialogRef.current = generateDialog;
+  selectedLayerIdRef.current = selectedLayerId;
+  selectedLayerIdsRef.current = selectedLayerIds;
+
+  useImageCanvasKeyboardShortcuts({
+    generateDialogRef,
+    selectedLayerIdRef,
+    selectedLayerIdsRef,
+    redoCanvasChange,
+    undoCanvasChange,
+    deleteLayerById,
+    deleteSelectedCanvasObjects,
+    requestRemoveCanvasGenerationDialog,
+    setActiveTool: (tool) => setActiveTool(tool),
+    setGenerateDialog: (updater) =>
+      setGenerateDialogState((currentDialog) =>
+        applyGenerateDialogUpdater(updater, currentDialog),
+      ),
+    setImageContextMenu: () => setImageContextMenuOpen(false),
+    setContextMenu: () => setContextMenuOpen(false),
+    setQuickEditPanel: (updater) =>
+      setQuickEditPanelState((currentPanel) =>
+        applyQuickEditPanelUpdater(updater, currentPanel),
+      ),
+    closeEditorChromePanels,
+    setIsSpecMenuOpen,
+    setIsGenerationReferenceMenuOpen,
+    setIsPublicationReferenceMenuOpen,
+    setIsPickingGenerationReferenceFromCanvas,
+    setIsPickingQuickEditReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+    setIsCharacterSpecMenuOpen,
+    setIsCharacterReferenceMenuOpen,
+    setIsPickingCharacterSpecFromCanvas,
+    setIsPickingCharacterReferenceFromCanvas,
+    setIsIconSpecMenuOpen,
+    setIsPickingIconSpecFromCanvas,
+    setIsUiDesignSpecMenuOpen,
+    setIsPickingUiDesignSpecFromCanvas,
+    setIsSpacePanning,
+    setShiftPressed,
+  });
+
+  return (
+    <div>
+      <input aria-label="快捷键输入框" />
+      <span data-testid="active-tool">{activeTool}</span>
+      <span data-testid="generate-dialog">
+        {generateDialog
+          ? `${generateDialog.mode}:${generateDialog.status}:${String(
+              generateDialog.composerOpen,
+            )}`
+          : 'none'}
+      </span>
+      <span data-testid="quick-edit">
+        {quickEditPanel ? quickEditPanel.status : 'none'}
+      </span>
+      <span data-testid="image-context">{String(imageContextMenuOpen)}</span>
+      <span data-testid="context-menu">{String(contextMenuOpen)}</span>
+      <span data-testid="spec-menu">{String(isSpecMenuOpen)}</span>
+      <span data-testid="publication-reference-menu">
+        {String(isPublicationReferenceMenuOpen)}
+      </span>
+      <span data-testid="publication-reference-picking">
+        {String(isPickingPublicationReferenceFromCanvas)}
+      </span>
+      <span data-testid="character-menu">
+        {String(isCharacterSpecMenuOpen)}
+      </span>
+      <span data-testid="character-reference-menu">
+        {String(isCharacterReferenceMenuOpen)}
+      </span>
+      <span data-testid="character-picking">
+        {String(isPickingCharacterSpecFromCanvas)}
+      </span>
+      <span data-testid="character-reference-picking">
+        {String(isPickingCharacterReferenceFromCanvas)}
+      </span>
+      <span data-testid="icon-menu">{String(isIconSpecMenuOpen)}</span>
+      <span data-testid="icon-picking">
+        {String(isPickingIconSpecFromCanvas)}
+      </span>
+      <span data-testid="space-panning">{String(isSpacePanning)}</span>
+      <span data-testid="shift-pressed">{String(shiftPressed)}</span>
+    </div>
+  );
+}
+
+describe('useImageCanvasKeyboardShortcuts', () => {
+  it('routes undo and redo shortcuts while ignoring editable inputs', () => {
+    const undoCanvasChange = vi.fn();
+    const redoCanvasChange = vi.fn();
+    render(
+      <KeyboardShortcutsHarness
+        undoCanvasChange={undoCanvasChange}
+        redoCanvasChange={redoCanvasChange}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'z', code: 'KeyZ', ctrlKey: true });
+    });
+    expect(undoCanvasChange).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      fireEvent.keyDown(window, {
+        key: 'Z',
+        code: 'KeyZ',
+        ctrlKey: true,
+        shiftKey: true,
+      });
+    });
+    expect(redoCanvasChange).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      fireEvent.keyDown(screen.getByLabelText('快捷键输入框'), {
+        key: 'z',
+        code: 'KeyZ',
+        ctrlKey: true,
+      });
+    });
+    expect(undoCanvasChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('deletes the selected layer with Backspace outside editable inputs', () => {
+    const deleteLayerById = vi.fn();
+    render(
+      <KeyboardShortcutsHarness
+        selectedLayerId="layer-selected"
+        selectedLayerIds={[]}
+        deleteLayerById={deleteLayerById}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(deleteLayerById).toHaveBeenCalledWith('layer-selected');
+  });
+
+  it('deletes complete canvas selection before falling back to active layer', () => {
+    const deleteLayerById = vi.fn();
+    const deleteSelectedCanvasObjects = vi.fn();
+    render(
+      <KeyboardShortcutsHarness
+        selectedLayerId="layer-selected"
+        selectedLayerIds={['layer-selected', 'generation-dialog:dialog-1']}
+        deleteLayerById={deleteLayerById}
+        deleteSelectedCanvasObjects={deleteSelectedCanvasObjects}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
+    });
+
+    expect(deleteSelectedCanvasObjects).toHaveBeenCalledTimes(1);
+    expect(deleteLayerById).not.toHaveBeenCalled();
+  });
+
+  it('requests deleting editable generation placeholders with Backspace', () => {
+    const requestRemoveCanvasGenerationDialog = vi.fn();
+    const dialog = createPlaceholderDialog('character');
+    render(
+      <KeyboardShortcutsHarness
+        initialTool="character"
+        initialGenerateDialog={dialog}
+        requestRemoveCanvasGenerationDialog={requestRemoveCanvasGenerationDialog}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(requestRemoveCanvasGenerationDialog).toHaveBeenCalledWith(dialog);
+    expect(screen.getByTestId('generate-dialog').textContent).toBe(
+      'character:idle:true',
+    );
+    expect(screen.getByTestId('active-tool').textContent).toBe('select');
+    expect(screen.getByTestId('character-menu').textContent).toBe('false');
+    expect(screen.getByTestId('character-picking').textContent).toBe('false');
+    expect(screen.getByTestId('icon-menu').textContent).toBe('false');
+    expect(screen.getByTestId('icon-picking').textContent).toBe('false');
+  });
+
+  it('requests deleting generating placeholders with Delete', () => {
+    const requestRemoveCanvasGenerationDialog = vi.fn();
+    const generatingDialog = createPlaceholderDialog('generate');
+    generatingDialog.status = 'generating';
+    render(
+      <KeyboardShortcutsHarness
+        initialTool="generate"
+        initialGenerateDialog={generatingDialog}
+        requestRemoveCanvasGenerationDialog={requestRemoveCanvasGenerationDialog}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' });
+    });
+
+    expect(requestRemoveCanvasGenerationDialog).toHaveBeenCalledWith(
+      generatingDialog,
+    );
+    expect(screen.getByTestId('active-tool').textContent).toBe('select');
+  });
+
+  it('removes audio generation placeholders with Backspace', () => {
+    const requestRemoveCanvasGenerationDialog = vi.fn();
+    render(
+      <KeyboardShortcutsHarness
+        initialTool="music"
+        initialGenerateDialog={createPlaceholderDialog('audio-sound-effect')}
+        requestRemoveCanvasGenerationDialog={requestRemoveCanvasGenerationDialog}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(requestRemoveCanvasGenerationDialog).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'dialog-1' }),
+    );
+    expect(screen.getByTestId('active-tool').textContent).toBe('select');
+  });
+
+  it('removes publication generation placeholders with Backspace', () => {
+    const requestRemoveCanvasGenerationDialog = vi.fn();
+    const dialog = createPlaceholderDialog('publication');
+    render(
+      <KeyboardShortcutsHarness
+        initialTool="publication"
+        initialGenerateDialog={dialog}
+        requestRemoveCanvasGenerationDialog={requestRemoveCanvasGenerationDialog}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Backspace', code: 'Backspace' });
+    });
+
+    expect(requestRemoveCanvasGenerationDialog).toHaveBeenCalledWith(dialog);
+    expect(screen.getByTestId('active-tool').textContent).toBe('select');
+    expect(screen.getByTestId('publication-reference-menu').textContent).toBe(
+      'false',
+    );
+    expect(
+      screen.getByTestId('publication-reference-picking').textContent,
+    ).toBe('false');
+  });
+
+  it('closes transient editor panels with Escape and collapses idle composers', () => {
+    const closeEditorChromePanels = vi.fn();
+    render(
+      <KeyboardShortcutsHarness
+        closeEditorChromePanels={closeEditorChromePanels}
+        initialGenerateDialog={createPlaceholderDialog('generate')}
+        initialQuickEditPanel={{
+          sourceLayerId: 'layer-source',
+          prompt: '局部修改',
+          size: '1024x1024',
+          model: 'mock',
+          status: 'idle',
+        }}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Escape', code: 'Escape' });
+    });
+
+    expect(closeEditorChromePanels).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId('generate-dialog').textContent).toBe(
+      'generate:idle:false',
+    );
+    expect(screen.getByTestId('quick-edit').textContent).toBe('none');
+    expect(screen.getByTestId('image-context').textContent).toBe('false');
+    expect(screen.getByTestId('context-menu').textContent).toBe('false');
+    expect(screen.getByTestId('spec-menu').textContent).toBe('false');
+    expect(screen.getByTestId('publication-reference-menu').textContent).toBe(
+      'false',
+    );
+    expect(
+      screen.getByTestId('publication-reference-picking').textContent,
+    ).toBe('false');
+    expect(screen.getByTestId('character-menu').textContent).toBe('false');
+    expect(screen.getByTestId('icon-menu').textContent).toBe('false');
+  });
+
+  it('collapses idle publication composer with Escape', () => {
+    render(
+      <KeyboardShortcutsHarness
+        initialGenerateDialog={createPlaceholderDialog('publication')}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Escape', code: 'Escape' });
+    });
+
+    expect(screen.getByTestId('generate-dialog').textContent).toBe(
+      'publication:idle:false',
+    );
+    expect(screen.getByTestId('publication-reference-menu').textContent).toBe(
+      'false',
+    );
+    expect(
+      screen.getByTestId('publication-reference-picking').textContent,
+    ).toBe('false');
+  });
+
+  it('keeps generating panels open when Escape closes transient chrome', () => {
+    const generatingDialog = createPlaceholderDialog('generate');
+    generatingDialog.status = 'generating';
+    render(
+      <KeyboardShortcutsHarness
+        initialGenerateDialog={generatingDialog}
+        initialQuickEditPanel={{
+          sourceLayerId: 'layer-source',
+          prompt: '继续修改',
+          size: '1024x1024',
+          model: 'mock',
+          status: 'generating',
+        }}
+      />,
+    );
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Escape', code: 'Escape' });
+    });
+
+    expect(screen.getByTestId('generate-dialog').textContent).toBe(
+      'generate:generating:true',
+    );
+    expect(screen.getByTestId('quick-edit').textContent).toBe('generating');
+  });
+
+  it('toggles temporary panning with Space outside editable inputs', () => {
+    render(<KeyboardShortcutsHarness />);
+
+    act(() => {
+      fireEvent.keyDown(window, { key: ' ', code: 'Space' });
+    });
+    expect(screen.getByTestId('space-panning').textContent).toBe('true');
+
+    act(() => {
+      fireEvent.keyUp(window, { key: ' ', code: 'Space' });
+    });
+    expect(screen.getByTestId('space-panning').textContent).toBe('false');
+
+    act(() => {
+      fireEvent.keyDown(screen.getByLabelText('快捷键输入框'), {
+        key: ' ',
+        code: 'Space',
+      });
+    });
+    expect(screen.getByTestId('space-panning').textContent).toBe('false');
+  });
+
+  it('tracks Shift key state', () => {
+    render(<KeyboardShortcutsHarness />);
+
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Shift', code: 'ShiftLeft' });
+    });
+    expect(screen.getByTestId('shift-pressed').textContent).toBe('true');
+
+    act(() => {
+      fireEvent.keyUp(window, { key: 'Shift', code: 'ShiftLeft' });
+    });
+    expect(screen.getByTestId('shift-pressed').textContent).toBe('false');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
new file mode 100644
index 000000000..a0aec9310
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasKeyboardShortcuts.ts
@@ -0,0 +1,298 @@
+import { type RefObject, useEffect } from 'react';
+
+import type {
+  CanvasGenerationDialogState,
+  GenerateDialogState,
+  QuickEditPanelState,
+} from './ImageCanvasEditorTypes';
+
+type UseImageCanvasKeyboardShortcutsOptions = {
+  generateDialogRef: RefObject<GenerateDialogState | null>;
+  selectedLayerIdRef: RefObject<string | null>;
+  selectedLayerIdsRef?: RefObject<string[]>;
+  redoCanvasChange: () => void;
+  undoCanvasChange: () => void;
+  deleteLayerById: (layerId: string | null) => void;
+  deleteSelectedCanvasObjects?: () => void;
+  requestRemoveCanvasGenerationDialog?: (
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  setActiveTool: (tool: 'select') => void;
+  setGenerateDialog: (
+    updater:
+      | GenerateDialogState
+      | null
+      | ((dialog: GenerateDialogState | null) => GenerateDialogState | null),
+  ) => void;
+  setImageContextMenu: (menu: null) => void;
+  setContextMenu: (menu: null) => void;
+  setQuickEditPanel: (
+    updater:
+      | QuickEditPanelState
+      | null
+      | ((
+          panel: QuickEditPanelState | null,
+        ) => QuickEditPanelState | null),
+  ) => void;
+  closeEditorChromePanels: () => void;
+  setIsSpecMenuOpen: (open: boolean) => void;
+  setIsGenerationReferenceMenuOpen: (open: boolean) => void;
+  setIsPublicationReferenceMenuOpen: (open: boolean) => void;
+  setIsPickingGenerationReferenceFromCanvas: (picking: boolean) => void;
+  setIsPickingQuickEditReferenceFromCanvas: (picking: boolean) => void;
+  setIsPickingPublicationReferenceFromCanvas: (picking: boolean) => void;
+  setIsCharacterSpecMenuOpen: (open: boolean) => void;
+  setIsCharacterReferenceMenuOpen: (open: boolean) => void;
+  setIsPickingCharacterSpecFromCanvas: (picking: boolean) => void;
+  setIsPickingCharacterReferenceFromCanvas: (picking: boolean) => void;
+  setIsIconSpecMenuOpen: (open: boolean) => void;
+  setIsPickingIconSpecFromCanvas: (picking: boolean) => void;
+  setIsUiDesignSpecMenuOpen: (open: boolean) => void;
+  setIsPickingUiDesignSpecFromCanvas: (picking: boolean) => void;
+  setIsSpacePanning: (panning: boolean) => void;
+  setShiftPressed: (pressed: boolean) => void;
+};
+
+function isEditableTarget(event: KeyboardEvent) {
+  const target = event.target as HTMLElement | null;
+  if (!target) {
+    return false;
+  }
+  if (target.tagName === 'AUDIO' || target.tagName === 'VIDEO') {
+    return false;
+  }
+  return (
+    target.tagName === 'INPUT' ||
+    target.tagName === 'TEXTAREA' ||
+    target.isContentEditable
+  );
+}
+
+function isCanvasGenerationPlaceholderDialog(
+  dialog: GenerateDialogState | null,
+) {
+  return (
+    Boolean(dialog?.placeholder) &&
+    (dialog?.mode === 'generate' ||
+      dialog?.mode === 'spec' ||
+      dialog?.mode === 'character' ||
+      dialog?.mode === 'icon' ||
+      dialog?.mode === 'ui-design' ||
+      dialog?.mode === 'quick-edit' ||
+      dialog?.mode === 'publication' ||
+      dialog?.mode === 'character-animation' ||
+      dialog?.mode === 'video' ||
+      dialog?.mode === 'audio-sound-effect' ||
+      dialog?.mode === 'audio-background-music')
+  );
+}
+
+function isCanvasGenerationDialogState(
+  dialog: GenerateDialogState | null,
+): dialog is CanvasGenerationDialogState {
+  return Boolean(dialog?.id && isCanvasGenerationPlaceholderDialog(dialog));
+}
+
+export function useImageCanvasKeyboardShortcuts({
+  generateDialogRef,
+  selectedLayerIdRef,
+  selectedLayerIdsRef,
+  redoCanvasChange,
+  undoCanvasChange,
+  deleteLayerById,
+  deleteSelectedCanvasObjects,
+  requestRemoveCanvasGenerationDialog,
+  setActiveTool,
+  setGenerateDialog,
+  setImageContextMenu,
+  setContextMenu,
+  setQuickEditPanel,
+  closeEditorChromePanels,
+  setIsSpecMenuOpen,
+  setIsGenerationReferenceMenuOpen,
+  setIsPublicationReferenceMenuOpen,
+  setIsPickingGenerationReferenceFromCanvas,
+  setIsPickingQuickEditReferenceFromCanvas,
+  setIsPickingPublicationReferenceFromCanvas,
+  setIsCharacterSpecMenuOpen,
+  setIsCharacterReferenceMenuOpen,
+  setIsPickingCharacterSpecFromCanvas,
+  setIsPickingCharacterReferenceFromCanvas,
+  setIsIconSpecMenuOpen,
+  setIsPickingIconSpecFromCanvas,
+  setIsUiDesignSpecMenuOpen,
+  setIsPickingUiDesignSpecFromCanvas,
+  setIsSpacePanning,
+  setShiftPressed,
+}: UseImageCanvasKeyboardShortcutsOptions) {
+  useEffect(() => {
+    const closeTransientEditorPanels = () => {
+      closeEditorChromePanels();
+      setIsSpecMenuOpen(false);
+      setIsGenerationReferenceMenuOpen(false);
+      setIsPublicationReferenceMenuOpen(false);
+      setIsPickingGenerationReferenceFromCanvas(false);
+      setIsPickingQuickEditReferenceFromCanvas(false);
+      setIsPickingPublicationReferenceFromCanvas(false);
+      setImageContextMenu(null);
+      setContextMenu(null);
+      setQuickEditPanel((currentPanel) =>
+        currentPanel?.status === 'generating' ? currentPanel : null,
+      );
+      setIsCharacterSpecMenuOpen(false);
+      setIsCharacterReferenceMenuOpen(false);
+      setIsPickingCharacterSpecFromCanvas(false);
+      setIsPickingCharacterReferenceFromCanvas(false);
+      setIsIconSpecMenuOpen(false);
+      setIsPickingIconSpecFromCanvas(false);
+      setIsUiDesignSpecMenuOpen(false);
+      setIsPickingUiDesignSpecFromCanvas(false);
+      setGenerateDialog((currentDialog) => {
+        if (!currentDialog || currentDialog.status === 'generating') {
+          return currentDialog;
+        }
+        if (
+          currentDialog.mode === 'generate' ||
+          currentDialog.mode === 'spec' ||
+          currentDialog.mode === 'ui-design' ||
+          currentDialog.mode === 'quick-edit' ||
+          currentDialog.mode === 'publication' ||
+          currentDialog.mode === 'character-animation' ||
+          currentDialog.mode === 'video'
+        ) {
+          return {
+            ...currentDialog,
+            composerOpen: false,
+          };
+        }
+        if (currentDialog.mode === 'character') {
+          return currentDialog;
+        }
+        if (currentDialog.mode === 'icon') {
+          return currentDialog;
+        }
+        return null;
+      });
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        (event.ctrlKey || event.metaKey) &&
+        event.code === 'KeyZ' &&
+        !isEditableTarget(event)
+      ) {
+        event.preventDefault();
+        if (event.shiftKey) {
+          redoCanvasChange();
+        } else {
+          undoCanvasChange();
+        }
+        return;
+      }
+      if (event.key === 'Shift') {
+        setShiftPressed(true);
+      }
+      if (
+        (event.key === 'Backspace' || event.key === 'Delete') &&
+        !event.repeat &&
+        !isEditableTarget(event)
+      ) {
+        if (selectedLayerIdsRef?.current.length) {
+          event.preventDefault();
+          deleteSelectedCanvasObjects?.();
+          return;
+        }
+        const currentSelectedLayerId = selectedLayerIdRef.current;
+        if (currentSelectedLayerId) {
+          event.preventDefault();
+          deleteLayerById(currentSelectedLayerId);
+          return;
+        }
+        if (isCanvasGenerationPlaceholderDialog(generateDialogRef.current)) {
+          event.preventDefault();
+          const currentDialog = generateDialogRef.current;
+          if (
+            isCanvasGenerationDialogState(currentDialog) &&
+            requestRemoveCanvasGenerationDialog
+          ) {
+            requestRemoveCanvasGenerationDialog(currentDialog);
+          } else {
+            setGenerateDialog(null);
+          }
+          setActiveTool('select');
+          setIsGenerationReferenceMenuOpen(false);
+          setIsPublicationReferenceMenuOpen(false);
+          setIsPickingGenerationReferenceFromCanvas(false);
+          setIsPickingQuickEditReferenceFromCanvas(false);
+          setIsPickingPublicationReferenceFromCanvas(false);
+          setIsCharacterSpecMenuOpen(false);
+          setIsCharacterReferenceMenuOpen(false);
+          setIsPickingCharacterSpecFromCanvas(false);
+          setIsPickingCharacterReferenceFromCanvas(false);
+          setIsIconSpecMenuOpen(false);
+          setIsPickingIconSpecFromCanvas(false);
+          setIsUiDesignSpecMenuOpen(false);
+          setIsPickingUiDesignSpecFromCanvas(false);
+          return;
+        }
+      }
+      if (event.key === 'Escape') {
+        closeTransientEditorPanels();
+        return;
+      }
+      if (event.code !== 'Space' || event.repeat || isEditableTarget(event)) {
+        return;
+      }
+      event.preventDefault();
+      setIsSpacePanning(true);
+    };
+    const handleKeyUp = (event: KeyboardEvent) => {
+      if (event.key === 'Shift') {
+        setShiftPressed(false);
+      }
+      if (event.code !== 'Space') {
+        return;
+      }
+      event.preventDefault();
+      setIsSpacePanning(false);
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('keyup', handleKeyUp);
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('keyup', handleKeyUp);
+    };
+  }, [
+    closeEditorChromePanels,
+    deleteSelectedCanvasObjects,
+    deleteLayerById,
+    generateDialogRef,
+    requestRemoveCanvasGenerationDialog,
+    redoCanvasChange,
+    selectedLayerIdRef,
+    selectedLayerIdsRef,
+    setActiveTool,
+    setContextMenu,
+    setGenerateDialog,
+    setImageContextMenu,
+    setIsGenerationReferenceMenuOpen,
+    setIsPublicationReferenceMenuOpen,
+    setIsPickingGenerationReferenceFromCanvas,
+    setIsPickingQuickEditReferenceFromCanvas,
+    setIsPickingPublicationReferenceFromCanvas,
+    setIsCharacterSpecMenuOpen,
+    setIsCharacterReferenceMenuOpen,
+    setIsIconSpecMenuOpen,
+    setIsPickingCharacterReferenceFromCanvas,
+    setIsPickingCharacterSpecFromCanvas,
+    setIsPickingIconSpecFromCanvas,
+    setIsPickingUiDesignSpecFromCanvas,
+    setIsSpacePanning,
+    setIsSpecMenuOpen,
+    setIsUiDesignSpecMenuOpen,
+    setQuickEditPanel,
+    setShiftPressed,
+    undoCanvasChange,
+  ]);
+}
diff --git a/src/components/image-editor/useImageCanvasLayerCommands.test.tsx b/src/components/image-editor/useImageCanvasLayerCommands.test.tsx
new file mode 100644
index 000000000..1af39cbe0
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasLayerCommands.test.tsx
@@ -0,0 +1,331 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasLayerCommands } from './useImageCanvasLayerCommands';
+
+function createLayer(id: string, x: number, zIndex: number): CanvasLayer {
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x,
+    y: 20,
+    width: 100,
+    height: 80,
+    originalWidth: 100,
+    originalHeight: 80,
+    zIndex,
+    sourceType: 'uploaded',
+  };
+}
+
+function LayerCommandsHarness({
+  exportLayerImage = vi.fn(),
+  onDeleteLayerSideEffects = vi.fn(),
+  onDeleteGenerationDialogSideEffects = vi.fn(),
+}: {
+  exportLayerImage?: (layer: CanvasLayer | null) => void;
+  onDeleteLayerSideEffects?: (layerId: string) => void;
+  onDeleteGenerationDialogSideEffects?: (dialogId: string) => void;
+}) {
+  const [layers, setLayers] = useState<CanvasLayer[]>([
+    createLayer('first', 10, 1),
+    createLayer('second', 160, 2),
+    createLayer('third', 310, 3),
+  ]);
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(
+    'first',
+  );
+  const [selectedLayerIds, setSelectedLayerIds] = useState<string[]>([
+    'first',
+    'second',
+  ]);
+  const [canvasGenerationDialogs] = useState<CanvasGenerationDialogState[]>([
+    {
+      id: 'dialog-1',
+      mode: 'generate',
+      prompt: '生成',
+      status: 'idle',
+      placeholder: {
+        x: 20,
+        y: 20,
+        width: 100,
+        height: 80,
+        originalWidth: 100,
+        originalHeight: 80,
+      },
+    },
+  ]);
+  const [metadataLayer, setMetadataLayer] = useState<CanvasLayer | null>(
+    layers[0] ?? null,
+  );
+  const [hoveredLayerId, setHoveredLayerId] = useState<string | null>('first');
+  const [contextMenu, setContextMenu] = useState<CanvasContextMenuState | null>(
+    {
+      kind: 'layer',
+      layerId: 'first',
+      x: 0,
+      y: 0,
+      canvasPoint: { x: 0, y: 0 },
+    },
+  );
+  const [historyCount, setHistoryCount] = useState(0);
+  const [imageContextClosedCount, setImageContextClosedCount] = useState(0);
+  const [activeTool, setActiveTool] = useState('select');
+
+  const selectSingleLayer = (layerId: string | null) => {
+    setSelectedLayerId(layerId);
+    setSelectedLayerIds(layerId ? [layerId] : []);
+  };
+
+  const commands = useImageCanvasLayerCommands({
+    layers,
+    contextMenu,
+    selectedLayerId,
+    selectedLayerIds,
+    canvasGenerationDialogs,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+    setHoveredLayerId,
+    setMetadataLayer,
+    setContextMenu,
+    setImageContextMenu: () =>
+      setImageContextClosedCount((currentCount) => currentCount + 1),
+    setActiveTool,
+    captureCanvasHistory: () =>
+      setHistoryCount((currentCount) => currentCount + 1),
+    selectSingleLayer,
+    onDeleteLayerSideEffects,
+    onDeleteGenerationDialogSideEffects,
+    exportLayerImage,
+  });
+
+  return (
+    <div>
+      <span data-testid="layers">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.title}:${layer.x}:${layer.zIndex}:${layer.groupId ?? '-'}:${layer.hidden ? 'hidden' : 'shown'}:${layer.locked ? 'locked' : 'open'}:${layer.flipX ? 'flipX' : '-'}:${layer.flipY ? 'flipY' : '-'}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="selection">
+        {selectedLayerId ?? '-'}:{selectedLayerIds.join(',')}
+      </span>
+      <span data-testid="metadata">{metadataLayer?.id ?? '-'}</span>
+      <span data-testid="hovered">{hoveredLayerId ?? '-'}</span>
+      <span data-testid="context">{contextMenu ? 'open' : 'closed'}</span>
+      <span data-testid="history">{historyCount}</span>
+      <span data-testid="image-context-closed">
+        {imageContextClosedCount}
+      </span>
+      <span data-testid="tool">{activeTool}</span>
+      <span data-testid="clipboard">
+        {commands.canvasClipboard
+          ? `${commands.canvasClipboard.mode}:${commands.canvasClipboard.layers.length}`
+          : '-'}
+      </span>
+      <button type="button" onClick={() => commands.copyContextLayers()}>
+        复制
+      </button>
+      <button
+        type="button"
+        onClick={() => commands.copyContextLayers({ cut: true })}
+      >
+        剪切
+      </button>
+      <button
+        type="button"
+        onClick={() => commands.pasteCanvasClipboard({ x: 500, y: 600 })}
+      >
+        粘贴
+      </button>
+      <button type="button" onClick={() => commands.duplicateContextLayers()}>
+        创建副本
+      </button>
+      <button type="button" onClick={() => commands.moveContextLayers('top')}>
+        置顶
+      </button>
+      <button type="button" onClick={() => commands.groupContextLayers()}>
+        创建组
+      </button>
+      <button type="button" onClick={() => commands.ungroupContextLayers()}>
+        解除组
+      </button>
+      <button
+        type="button"
+        onClick={() => commands.toggleContextLayerVisibility()}
+      >
+        显隐
+      </button>
+      <button type="button" onClick={() => commands.toggleContextLayerLock()}>
+        锁定
+      </button>
+      <button type="button" onClick={() => commands.flipContextLayers('x')}>
+        翻转
+      </button>
+      <button type="button" onClick={() => commands.deleteContextLayers()}>
+        删除右键目标
+      </button>
+      <button type="button" onClick={() => commands.deleteSelectedLayer()}>
+        删除选中
+      </button>
+      <button type="button" onClick={() => commands.deleteLayerById('first')}>
+        删除单图
+      </button>
+      <button type="button" onClick={() => commands.groupSelectedLayers()}>
+        选中打组
+      </button>
+      <button type="button" onClick={() => commands.exportContextLayer()}>
+        导出
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setContextMenu({
+            kind: 'layer',
+            layerId: 'third',
+            x: 0,
+            y: 0,
+            canvasPoint: { x: 0, y: 0 },
+          })
+        }
+      >
+        右键第三层
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          setSelectedLayerId('third');
+          setSelectedLayerIds(['third']);
+        }}
+      >
+        只选第三层
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          setSelectedLayerId('first');
+          setSelectedLayerIds(['first', 'generation-dialog:dialog-1']);
+        }}
+      >
+        混合选择
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasLayerCommands', () => {
+  it('copies, cuts, and pastes context layers with history and selection updates', () => {
+    render(<LayerCommandsHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '复制' }));
+    expect(screen.getByTestId('clipboard').textContent).toBe('copy:2');
+    expect(screen.getByTestId('context').textContent).toBe('closed');
+
+    fireEvent.click(screen.getByRole('button', { name: '粘贴' }));
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'first 副本:500:4',
+    );
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'second 副本:650:5',
+    );
+    expect(screen.getByTestId('selection').textContent).toContain(
+      'layer-copy-',
+    );
+    expect(screen.getByTestId('tool').textContent).toBe('select');
+
+    fireEvent.click(screen.getByRole('button', { name: '右键第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '只选第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '剪切' }));
+
+    expect(screen.getByTestId('clipboard').textContent).toBe('cut:1');
+    expect(screen.getByTestId('layers').textContent).not.toContain('third');
+    expect(screen.getByTestId('selection').textContent).toBe('-:');
+    expect(Number(screen.getByTestId('history').textContent)).toBeGreaterThan(
+      1,
+    );
+  });
+
+  it('applies layer commands and clears menus without owning menu positioning', () => {
+    const exportLayerImage = vi.fn();
+    render(<LayerCommandsHarness exportLayerImage={exportLayerImage} />);
+
+    fireEvent.click(screen.getByRole('button', { name: '创建组' }));
+    expect(screen.getByTestId('layers').textContent).toContain('layer-group-');
+
+    fireEvent.click(screen.getByRole('button', { name: '右键第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '显隐' }));
+    expect(screen.getByTestId('layers').textContent).toContain(':hidden:');
+
+    fireEvent.click(screen.getByRole('button', { name: '右键第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '锁定' }));
+    expect(screen.getByTestId('layers').textContent).toContain(':locked:');
+
+    fireEvent.click(screen.getByRole('button', { name: '右键第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '翻转' }));
+    expect(screen.getByTestId('layers').textContent).toContain(':flipX:');
+
+    fireEvent.click(screen.getByRole('button', { name: '右键第三层' }));
+    fireEvent.click(screen.getByRole('button', { name: '导出' }));
+    expect(exportLayerImage).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'third' }),
+    );
+    expect(screen.getByTestId('context').textContent).toBe('closed');
+  });
+
+  it('deletes selected and direct layers while running delete side effects', () => {
+    const onDeleteLayerSideEffects = vi.fn();
+    render(
+      <LayerCommandsHarness
+        onDeleteLayerSideEffects={onDeleteLayerSideEffects}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '删除选中' }));
+
+    expect(screen.getByTestId('layers').textContent).not.toContain('first');
+    expect(screen.getByTestId('layers').textContent).not.toContain('second');
+    expect(screen.getByTestId('selection').textContent).toBe('third:third');
+    expect(screen.getByTestId('metadata').textContent).toBe('-');
+    expect(screen.getByTestId('image-context-closed').textContent).toBe('1');
+    expect(onDeleteLayerSideEffects).toHaveBeenCalledWith('first');
+    expect(onDeleteLayerSideEffects).toHaveBeenCalledWith('second');
+
+    fireEvent.click(screen.getByRole('button', { name: '删除单图' }));
+    expect(screen.getByTestId('image-context-closed').textContent).toBe('2');
+  });
+
+  it('deletes selected generation dialogs together with layer targets', () => {
+    const onDeleteLayerSideEffects = vi.fn();
+    const onDeleteGenerationDialogSideEffects = vi.fn();
+    render(
+      <LayerCommandsHarness
+        onDeleteLayerSideEffects={onDeleteLayerSideEffects}
+        onDeleteGenerationDialogSideEffects={onDeleteGenerationDialogSideEffects}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '混合选择' }));
+    fireEvent.click(screen.getByRole('button', { name: '删除选中' }));
+
+    expect(screen.getByTestId('layers').textContent).not.toContain('first');
+    expect(screen.getByTestId('layers').textContent).toContain('second');
+    expect(screen.getByTestId('selection').textContent).toBe('-:');
+    expect(onDeleteLayerSideEffects).toHaveBeenCalledWith('first');
+    expect(onDeleteGenerationDialogSideEffects).toHaveBeenCalledWith(
+      'dialog-1',
+    );
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasLayerCommands.ts b/src/components/image-editor/useImageCanvasLayerCommands.ts
new file mode 100644
index 000000000..2bc968522
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasLayerCommands.ts
@@ -0,0 +1,456 @@
+import {
+  useCallback,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
+
+import type {
+  CanvasClipboard,
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+} from './ImageCanvasEditorTypes';
+import {
+  createCanvasLayerClipboard,
+  duplicateCanvasLayers,
+  flipCanvasLayers,
+  getCanvasLayersByIds,
+  groupCanvasLayers,
+  moveCanvasLayers,
+  removeCanvasLayers,
+  resolveContextTargetLayerIds,
+  toggleCanvasLayersLock,
+  toggleCanvasLayersVisibility,
+  ungroupCanvasLayers,
+  updateCanvasLayersByIds,
+  type CanvasLayerFlipAxis,
+  type CanvasLayerMoveMode,
+} from './ImageCanvasLayerCommandModel';
+import {
+  getCanvasGenerationDialogIdFromSelectionId,
+  getSelectedLayerIds,
+} from './ImageCanvasSelectionModel';
+
+type LayerCommandsOptions = {
+  layers: CanvasLayer[];
+  contextMenu: CanvasContextMenuState | null;
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  canvasGenerationDialogs?: CanvasGenerationDialogState[];
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  setSelectedLayerId: Dispatch<SetStateAction<string | null>>;
+  setSelectedLayerIds: Dispatch<SetStateAction<string[]>>;
+  setHoveredLayerId: Dispatch<SetStateAction<string | null>>;
+  setMetadataLayer: Dispatch<SetStateAction<CanvasLayer | null>>;
+  setContextMenu: Dispatch<SetStateAction<CanvasContextMenuState | null>>;
+  setImageContextMenu: (menu: null) => void;
+  setActiveTool: (tool: 'select') => void;
+  captureCanvasHistory: () => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  onDeleteLayerSideEffects: (targetLayerId: string) => void;
+  onDeleteGenerationDialogSideEffects?: (targetDialogId: string) => void;
+  exportLayerImage: (layer: CanvasLayer | null) => void;
+};
+
+function createGroupId() {
+  return `layer-group-${Date.now()}`;
+}
+
+export function useImageCanvasLayerCommands({
+  layers,
+  contextMenu,
+  selectedLayerId,
+  selectedLayerIds,
+  canvasGenerationDialogs = [],
+  setLayers,
+  setSelectedLayerId,
+  setSelectedLayerIds,
+  setHoveredLayerId,
+  setMetadataLayer,
+  setContextMenu,
+  setImageContextMenu,
+  setActiveTool,
+  captureCanvasHistory,
+  selectSingleLayer,
+  onDeleteLayerSideEffects,
+  onDeleteGenerationDialogSideEffects,
+  exportLayerImage,
+}: LayerCommandsOptions) {
+  const [canvasClipboard, setCanvasClipboard] =
+    useState<CanvasClipboard | null>(null);
+
+  const getContextTargetLayerIds = useCallback(
+    (menu: CanvasContextMenuState | null = contextMenu) =>
+      resolveContextTargetLayerIds(menu, selectedLayerIds),
+    [contextMenu, selectedLayerIds],
+  );
+
+  const duplicateLayersToPoint = useCallback(
+    (
+      sourceLayers: CanvasLayer[],
+      canvasPoint?: { x: number; y: number },
+      options: { renameCopies?: boolean } = {},
+    ) =>
+      duplicateCanvasLayers({
+        sourceLayers,
+        allLayers: layers,
+        canvasPoint,
+        renameCopies: options.renameCopies !== false,
+      }),
+    [layers],
+  );
+
+  const pasteCanvasClipboard = useCallback(
+    (canvasPoint?: { x: number; y: number }) => {
+      if (!canvasClipboard?.layers.length) {
+        return;
+      }
+      const nextLayers = duplicateLayersToPoint(
+        canvasClipboard.layers,
+        canvasPoint,
+        {
+          renameCopies: canvasClipboard.mode !== 'cut',
+        },
+      );
+      if (!nextLayers.length) {
+        return;
+      }
+      captureCanvasHistory();
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
+      setSelectedLayerIds(nextLayers.map((layer) => layer.id));
+      setSelectedLayerId(nextLayers[0]?.id ?? null);
+      setActiveTool('select');
+      setContextMenu(null);
+    },
+    [
+      canvasClipboard,
+      captureCanvasHistory,
+      duplicateLayersToPoint,
+      setActiveTool,
+      setContextMenu,
+      setLayers,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    ],
+  );
+
+  const copyContextLayers = useCallback(
+    (options: { cut?: boolean } = {}) => {
+      const targetIds = getContextTargetLayerIds();
+      const clipboard = createCanvasLayerClipboard(
+        layers,
+        targetIds,
+        options.cut ? 'cut' : 'copy',
+      );
+      if (!clipboard) {
+        return;
+      }
+      setCanvasClipboard(clipboard);
+      if (options.cut) {
+        captureCanvasHistory();
+        setLayers((currentLayers) =>
+          removeCanvasLayers(currentLayers, targetIds),
+        );
+        selectSingleLayer(null);
+        setMetadataLayer((currentLayer) =>
+          currentLayer && targetIds.includes(currentLayer.id)
+            ? null
+            : currentLayer,
+        );
+      }
+      setContextMenu(null);
+    },
+    [
+      captureCanvasHistory,
+      getContextTargetLayerIds,
+      layers,
+      selectSingleLayer,
+      setContextMenu,
+      setLayers,
+      setMetadataLayer,
+    ],
+  );
+
+  const duplicateContextLayers = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    const targetLayers = getCanvasLayersByIds(layers, targetIds);
+    const nextLayers = duplicateLayersToPoint(targetLayers);
+    if (!nextLayers.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
+    setSelectedLayerIds(nextLayers.map((layer) => layer.id));
+    setSelectedLayerId(nextLayers[0]?.id ?? null);
+    setContextMenu(null);
+  }, [
+    captureCanvasHistory,
+    duplicateLayersToPoint,
+    getContextTargetLayerIds,
+    layers,
+    setContextMenu,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+  ]);
+
+  const updateContextLayers = useCallback(
+    (updater: (layer: CanvasLayer, targetIds: string[]) => CanvasLayer) => {
+      const targetIds = getContextTargetLayerIds();
+      if (!targetIds.length) {
+        return;
+      }
+      captureCanvasHistory();
+      setLayers((currentLayers) =>
+        updateCanvasLayersByIds(currentLayers, targetIds, updater),
+      );
+      setContextMenu(null);
+    },
+    [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers],
+  );
+
+  const moveContextLayers = useCallback(
+    (mode: CanvasLayerMoveMode) => {
+      const targetIds = getContextTargetLayerIds();
+      if (!targetIds.length) {
+        return;
+      }
+      captureCanvasHistory();
+      setLayers((currentLayers) =>
+        moveCanvasLayers(currentLayers, targetIds, mode),
+      );
+      setContextMenu(null);
+    },
+    [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers],
+  );
+
+  const groupContextLayers = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    if (!targetIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) =>
+      groupCanvasLayers(currentLayers, targetIds, createGroupId()),
+    );
+    setContextMenu(null);
+  }, [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers]);
+
+  const ungroupContextLayers = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    if (!targetIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) => ungroupCanvasLayers(currentLayers, targetIds));
+    setContextMenu(null);
+  }, [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers]);
+
+  const toggleContextLayerVisibility = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    if (!targetIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) =>
+      toggleCanvasLayersVisibility(currentLayers, targetIds),
+    );
+    setContextMenu(null);
+  }, [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers]);
+
+  const toggleContextLayerLock = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    if (!targetIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) =>
+      toggleCanvasLayersLock(currentLayers, targetIds),
+    );
+    setContextMenu(null);
+  }, [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers]);
+
+  const flipContextLayers = useCallback(
+    (axis: CanvasLayerFlipAxis) => {
+      const targetIds = getContextTargetLayerIds();
+      if (!targetIds.length) {
+        return;
+      }
+      captureCanvasHistory();
+      setLayers((currentLayers) =>
+        flipCanvasLayers(currentLayers, targetIds, axis),
+      );
+      setContextMenu(null);
+    },
+    [captureCanvasHistory, getContextTargetLayerIds, setContextMenu, setLayers],
+  );
+
+  const deleteContextLayers = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    if (!targetIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) => removeCanvasLayers(currentLayers, targetIds));
+    selectSingleLayer(null);
+    setHoveredLayerId(null);
+    setMetadataLayer((currentLayer) =>
+      currentLayer && targetIds.includes(currentLayer.id) ? null : currentLayer,
+    );
+    setContextMenu(null);
+  }, [
+    captureCanvasHistory,
+    getContextTargetLayerIds,
+    selectSingleLayer,
+    setContextMenu,
+    setHoveredLayerId,
+    setLayers,
+    setMetadataLayer,
+  ]);
+
+  const exportContextLayer = useCallback(() => {
+    const targetIds = getContextTargetLayerIds();
+    const targetLayer = layers.find((layer) => targetIds.includes(layer.id));
+    exportLayerImage(targetLayer ?? null);
+    setContextMenu(null);
+  }, [exportLayerImage, getContextTargetLayerIds, layers, setContextMenu]);
+
+  const deleteLayerById = useCallback(
+    (targetLayerId: string | null) => {
+      if (!targetLayerId) {
+        return;
+      }
+      setImageContextMenu(null);
+      setContextMenu(null);
+      captureCanvasHistory();
+      setLayers((currentLayers) => {
+        const nextLayers = currentLayers.filter(
+          (layer) => layer.id !== targetLayerId,
+        );
+        const nextSelectedLayer = nextLayers
+          .slice()
+          .sort((left, right) => right.zIndex - left.zIndex)[0];
+        selectSingleLayer(nextSelectedLayer?.id ?? null);
+        return nextLayers;
+      });
+      setHoveredLayerId(null);
+      setMetadataLayer((currentLayer) =>
+        currentLayer?.id === targetLayerId ? null : currentLayer,
+      );
+      onDeleteLayerSideEffects(targetLayerId);
+    },
+    [
+      captureCanvasHistory,
+      onDeleteLayerSideEffects,
+      selectSingleLayer,
+      setContextMenu,
+      setHoveredLayerId,
+      setImageContextMenu,
+      setLayers,
+      setMetadataLayer,
+    ],
+  );
+
+  const deleteSelectedLayer = useCallback(() => {
+    const targetIds = selectedLayerIds.length
+      ? selectedLayerIds
+      : selectedLayerId
+        ? [selectedLayerId]
+        : [];
+    const targetLayerIds = getSelectedLayerIds(targetIds);
+    const targetDialogIds = targetIds
+      .map(getCanvasGenerationDialogIdFromSelectionId)
+      .filter((dialogId): dialogId is string => Boolean(dialogId))
+      .filter((dialogId) =>
+        canvasGenerationDialogs.some((dialog) => dialog.id === dialogId),
+      );
+    if (!targetLayerIds.length && !targetDialogIds.length) {
+      return;
+    }
+    if (targetLayerIds.length === 1 && !targetDialogIds.length) {
+      deleteLayerById(targetLayerIds[0] ?? null);
+      return;
+    }
+    captureCanvasHistory();
+    setImageContextMenu(null);
+    setContextMenu(null);
+    if (targetLayerIds.length) {
+      setLayers((currentLayers) => {
+        const nextLayers = currentLayers.filter(
+          (layer) => !targetLayerIds.includes(layer.id),
+        );
+        if (!targetDialogIds.length) {
+          const nextSelectedLayer = nextLayers
+            .slice()
+            .sort((left, right) => right.zIndex - left.zIndex)[0];
+          selectSingleLayer(nextSelectedLayer?.id ?? null);
+        }
+        return nextLayers;
+      });
+    }
+    if (targetDialogIds.length || !targetLayerIds.length) {
+      selectSingleLayer(null);
+    }
+    setHoveredLayerId(null);
+    setMetadataLayer((currentLayer) =>
+      currentLayer && targetLayerIds.includes(currentLayer.id)
+        ? null
+        : currentLayer,
+    );
+    targetLayerIds.forEach((targetId) => onDeleteLayerSideEffects(targetId));
+    targetDialogIds.forEach((targetId) =>
+      onDeleteGenerationDialogSideEffects?.(targetId),
+    );
+  }, [
+    captureCanvasHistory,
+    canvasGenerationDialogs,
+    deleteLayerById,
+    onDeleteGenerationDialogSideEffects,
+    onDeleteLayerSideEffects,
+    selectSingleLayer,
+    selectedLayerId,
+    selectedLayerIds,
+    setContextMenu,
+    setHoveredLayerId,
+    setImageContextMenu,
+    setLayers,
+    setMetadataLayer,
+  ]);
+
+  const groupSelectedLayers = useCallback(() => {
+    const targetIds = selectedLayerIds.length
+      ? selectedLayerIds
+      : selectedLayerId
+        ? [selectedLayerId]
+        : [];
+    const targetLayerIds = getSelectedLayerIds(targetIds);
+    if (!targetLayerIds.length) {
+      return;
+    }
+    captureCanvasHistory();
+    setLayers((currentLayers) =>
+      groupCanvasLayers(currentLayers, targetLayerIds, createGroupId()),
+    );
+  }, [captureCanvasHistory, selectedLayerId, selectedLayerIds, setLayers]);
+
+  return {
+    canvasClipboard,
+    getContextTargetLayerIds,
+    pasteCanvasClipboard,
+    copyContextLayers,
+    duplicateContextLayers,
+    updateContextLayers,
+    moveContextLayers,
+    groupContextLayers,
+    ungroupContextLayers,
+    toggleContextLayerVisibility,
+    toggleContextLayerLock,
+    flipContextLayers,
+    deleteContextLayers,
+    exportContextLayer,
+    deleteLayerById,
+    deleteSelectedLayer,
+    groupSelectedLayers,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx b/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx
new file mode 100644
index 000000000..de86a8a85
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasProjectPersistence.test.tsx
@@ -0,0 +1,650 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasProjectPersistence } from './useImageCanvasProjectPersistence';
+
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const loadEditorProjectMock = vi.hoisted(() => vi.fn());
+const loadOrCreateRecentEditorProjectMock = vi.hoisted(() => vi.fn());
+const saveEditorProjectLayoutMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    createEditorProjectResource: createEditorProjectResourceMock,
+    loadEditorProject: loadEditorProjectMock,
+    loadOrCreateRecentEditorProject: loadOrCreateRecentEditorProjectMock,
+    saveEditorProjectLayout: saveEditorProjectLayoutMock,
+  };
+});
+
+function createLayer(
+  id: string,
+  overrides: Partial<CanvasLayer> = {},
+): CanvasLayer {
+  return {
+    id,
+    resourceId: `local-${id}`,
+    title: '账号素材A',
+    src: 'data:image/png;base64,YQ==',
+    x: 10,
+    y: 20,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 3,
+    sourceType: 'uploaded',
+    sourceAssetId: 'asset-a',
+    ...overrides,
+  };
+}
+
+function ProjectPersistenceHarness({
+  canAccessProtectedData = true,
+  initialGenerationDialogs = [],
+}: {
+  canAccessProtectedData?: boolean;
+  initialGenerationDialogs?: CanvasGenerationDialogState[];
+}) {
+  const [layers, setLayers] = useState<CanvasLayer[]>([]);
+  const [generationDialogs, setGenerationDialogs] = useState<
+    CanvasGenerationDialogState[]
+  >(initialGenerationDialogs);
+  const [viewport, setViewport] = useState<CanvasViewport>({
+    x: 0,
+    y: 0,
+    scale: 1,
+  });
+  const [projectTitle, setProjectTitle] = useState('');
+  const [projectRenameValue, setProjectRenameValue] = useState('');
+  const layersRef = useRef(layers);
+  const viewportRef = useRef(viewport);
+  const canvasGenerationDialogsRef = useRef(generationDialogs);
+  const selectedLayerRef = useRef<string | null>(null);
+  const layerCounterRef = useRef(0);
+  const openEditorLoginModalRef = useRef(vi.fn());
+
+  layersRef.current = layers;
+  viewportRef.current = viewport;
+  canvasGenerationDialogsRef.current = generationDialogs;
+  const selectSingleLayer = useCallback((layerId: string | null) => {
+    selectedLayerRef.current = layerId;
+  }, []);
+  const setLayerCounter = useCallback((value: number) => {
+    layerCounterRef.current = value;
+  }, []);
+  const persistenceRefs = useMemo(
+    () => ({
+      layersRef,
+      viewportRef,
+      canvasGenerationDialogsRef,
+    }),
+    [],
+  );
+  const persistenceSetters = useMemo(
+    () => ({
+      setProjectTitle,
+      setProjectRenameValue,
+      setViewport,
+      setLayers,
+      selectSingleLayer,
+      setLayerCounter,
+      restoreCanvasGenerationDialogs: setGenerationDialogs,
+    }),
+    [selectSingleLayer, setLayerCounter],
+  );
+
+  const persistence = useImageCanvasProjectPersistence({
+    refs: persistenceRefs,
+    setters: persistenceSetters,
+    layers,
+    canvasGenerationDialogs: generationDialogs,
+    viewport,
+    canAccessProtectedData,
+    openEditorLoginModal: openEditorLoginModalRef.current,
+  });
+
+  return (
+    <div>
+      <span data-testid="project-id">{persistence.projectId ?? '-'}</span>
+      <span data-testid="project-title">{projectTitle}</span>
+      <span data-testid="project-rename">{projectRenameValue}</span>
+      <span data-testid="layers">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.resourceId}:${layer.assetKind ?? '-'}:${
+                layer.generationInputs?.fields[0]?.value ?? '-'
+              }:${layer.objectKey ?? '-'}:${layer.assetObjectId ?? '-'}`,
+          )
+          .join(',')}
+      </span>
+      <span data-testid="selected">{selectedLayerRef.current ?? '-'}</span>
+      <span data-testid="counter">{layerCounterRef.current}</span>
+      <span data-testid="generation-dialogs">
+        {generationDialogs
+          .map((dialog) => `${dialog.id}:${dialog.prompt}:${dialog.placeholder?.x}`)
+          .join(',')}
+      </span>
+      <button
+        type="button"
+        onClick={() => {
+          persistence.appendCanvasLayersWithResources([createLayer('layer-a')]);
+        }}
+      >
+        append
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          persistence.appendCanvasLayersWithResources([
+            createLayer('layer-server-resource', {
+              resourceId: 'resource-from-generation-bff',
+              title: '后端已保存图片',
+              sourceType: 'generated',
+            }),
+          ]);
+        }}
+      >
+        append server resource
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          persistence.appendCanvasLayersWithResources([
+            createLayer('layer-character', {
+              title: '角色形象',
+              sourceType: 'generated',
+              assetKind: 'character',
+              generationInputs: {
+                fields: [{ title: '角色设定', value: '银发游侠' }],
+                references: [],
+              },
+            }),
+          ]);
+        }}
+      >
+        append character
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          persistence.appendCanvasLayersWithResources([
+            createLayer('layer-private-object', {
+              src: 'https://signed.example.test/private.png?expires=1',
+              objectKey: 'generated-character-drafts/editor/private.png',
+              title: '私有对象素材',
+              sourceType: 'generated',
+            }),
+          ]);
+        }}
+      >
+        append private object
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          const generatedLayer = createLayer('layer-generated');
+          persistence.appendCanvasLayersWithResources([
+            {
+              ...generatedLayer,
+              title: '生成图片',
+              sourceType: 'generated',
+              sourceAssetId: undefined,
+            },
+          ]);
+        }}
+      >
+        append generated
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          setGenerationDialogs((currentDialogs) =>
+            currentDialogs.map((dialog) =>
+              dialog.id === 'generation-dialog-1'
+                ? {
+                    ...dialog,
+                    prompt: '移动后的生成器',
+                    placeholder: dialog.placeholder
+                      ? { ...dialog.placeholder, x: 88 }
+                      : dialog.placeholder,
+                  }
+                : dialog,
+            ),
+          );
+        }}
+      >
+        move generation
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasProjectPersistence', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadOrCreateRecentEditorProjectMock.mockResolvedValue({
+      projectId: 'editor-project-default',
+      title: '空画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    createEditorProjectResourceMock.mockResolvedValue({
+      resourceId: 'resource-added-asset-a',
+      projectId: 'editor-project-default',
+      imageSrc: 'data:image/png;base64,YQ==',
+      width: 320,
+      height: 240,
+      sourceType: 'uploaded',
+    });
+    saveEditorProjectLayoutMock.mockResolvedValue({
+      projectId: 'editor-project-default',
+      title: '空画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+  });
+
+  it('saves appended layers with the server resource id immediately after resource creation', async () => {
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    expect(screen.getByTestId('project-title').textContent).toBe('空画布项目');
+    expect(screen.getByTestId('project-rename').textContent).toBe(
+      '空画布项目',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'append' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe(
+      'layer-a:local-layer-a:-:-:-:-',
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toBe(
+        'layer-a:resource-added-asset-a:-:-:-:-',
+      );
+    });
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              layerId: 'layer-a',
+              resourceId: 'resource-added-asset-a',
+              sourceAssetId: 'asset-a',
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('does not create a project resource again for backend-persisted generated layers', async () => {
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    act(() => {
+      screen.getByRole('button', { name: 'append server resource' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe(
+      'layer-server-resource:resource-from-generation-bff:-:-:-:-',
+    );
+    expect(createEditorProjectResourceMock).not.toHaveBeenCalled();
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              layerId: 'layer-server-resource',
+              resourceId: 'resource-from-generation-bff',
+              sourceType: 'generated',
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('persists generated layer metadata on the project resource and restores it from resources', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '已有角色项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          layerId: 'layer-character',
+          resourceId: 'resource-character',
+          title: '角色形象',
+          x: 10,
+          y: 20,
+          width: 320,
+          height: 240,
+          originalWidth: 320,
+          originalHeight: 240,
+          zIndex: 3,
+          sourceType: 'generated',
+        },
+      ],
+      resources: [
+        {
+          resourceId: 'resource-character',
+          projectId: 'editor-project-default',
+          imageSrc: '/generated/character.png',
+          objectKey: 'generated/character.png',
+          assetObjectId: 'asset-object-character',
+          width: 320,
+          height: 240,
+          sourceType: 'generated',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '银发游侠' }],
+            references: [],
+          },
+        },
+      ],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+    createEditorProjectResourceMock.mockResolvedValueOnce({
+      resourceId: 'resource-character-new',
+      projectId: 'editor-project-default',
+      imageSrc: 'data:image/png;base64,YQ==',
+      width: 320,
+      height: 240,
+      sourceType: 'generated',
+      assetKind: 'character',
+      generationInputs: {
+        fields: [{ title: '角色设定', value: '银发游侠' }],
+        references: [],
+      },
+    });
+
+    render(<ProjectPersistenceHarness />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('layers').textContent).toBe(
+        'layer-character:resource-character:character:银发游侠:generated/character.png:asset-object-character',
+      );
+    });
+    act(() => {
+      screen.getByRole('button', { name: 'append character' }).click();
+    });
+
+    await waitFor(() => {
+      expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          sourceType: 'generated',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '银发游侠' }],
+            references: [],
+          },
+        }),
+      );
+    });
+  });
+
+  it('creates project resources from objectKey without posting heavy signed URLs', async () => {
+    createEditorProjectResourceMock.mockResolvedValueOnce({
+      resourceId: 'resource-private-object',
+      projectId: 'editor-project-default',
+      imageSrc: '/generated-character-drafts/editor/private.png',
+      objectKey: 'generated-character-drafts/editor/private.png',
+      width: 320,
+      height: 240,
+      sourceType: 'generated',
+    });
+
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    act(() => {
+      screen.getByRole('button', { name: 'append private object' }).click();
+    });
+
+    await waitFor(() => {
+      expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          imageSrc: '/generated-character-drafts/editor/private.png',
+          objectKey: 'generated-character-drafts/editor/private.png',
+        }),
+      );
+    });
+  });
+
+  it('saves generation dialogs in the project layout and restores them on load', async () => {
+    const savedDialog: CanvasGenerationDialogState = {
+      id: 'generation-dialog-1',
+      mode: 'generate',
+      prompt: '刷新后继续生成',
+      status: 'generating',
+      composerOpen: false,
+      placeholder: {
+        x: 42,
+        y: 56,
+        width: 420,
+        height: 420,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+    };
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '空画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-1',
+          resourceId: 'generation-dialog:generation-dialog-1',
+          dialog: savedDialog,
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    await waitFor(() => {
+      expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+        'generation-dialog-1:刷新后继续生成:42',
+      );
+    });
+
+    vi.useFakeTimers();
+    act(() => {
+      screen.getByRole('button', { name: 'move generation' }).click();
+    });
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-1:移动后的生成器:88',
+    );
+    act(() => {
+      vi.advanceTimersByTime(451);
+    });
+
+    expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+      'editor-project-default',
+      expect.objectContaining({
+        layers: expect.arrayContaining([
+          expect.objectContaining({
+            itemType: 'generation-dialog',
+            dialog: expect.objectContaining({
+              id: 'generation-dialog-1',
+              prompt: '移动后的生成器',
+              placeholder: expect.objectContaining({ x: 88 }),
+            }),
+          }),
+        ]),
+      }),
+    );
+    vi.useRealTimers();
+  });
+
+  it('saves generated layers together with their generator snapshots', async () => {
+    const savedDialog: CanvasGenerationDialogState = {
+      id: 'generation-dialog-1',
+      mode: 'generate',
+      prompt: '已生成也要保存生成器',
+      status: 'idle',
+      composerOpen: true,
+      generatedLayerId: 'layer-generated',
+      placeholder: {
+        x: 70,
+        y: 80,
+        width: 420,
+        height: 420,
+        originalWidth: 2048,
+        originalHeight: 2048,
+      },
+    };
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '空画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-1',
+          resourceId: 'generation-dialog:generation-dialog-1',
+          dialog: savedDialog,
+        },
+      ],
+      resources: [],
+      updatedAt: '2026-06-12T00:00:00.000Z',
+    });
+
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-1:已生成也要保存生成器:70',
+    );
+    act(() => {
+      screen.getByRole('button', { name: 'append generated' }).click();
+    });
+
+    await waitFor(() => {
+      expect(saveEditorProjectLayoutMock).toHaveBeenCalledWith(
+        'editor-project-default',
+        expect.objectContaining({
+          layers: expect.arrayContaining([
+            expect.objectContaining({
+              layerId: 'layer-generated',
+              sourceType: 'generated',
+            }),
+            expect.objectContaining({
+              itemType: 'generation-dialog',
+              dialog: expect.objectContaining({
+                id: 'generation-dialog-1',
+                generatedLayerId: 'layer-generated',
+                prompt: '已生成也要保存生成器',
+                placeholder: expect.objectContaining({
+                  x: 70,
+                  width: 420,
+                }),
+              }),
+            }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  it('keeps backend layout as the project truth when loading generating dialogs', async () => {
+    loadOrCreateRecentEditorProjectMock.mockResolvedValueOnce({
+      projectId: 'editor-project-default',
+      title: '角色画布项目',
+      viewport: { x: 0, y: 0, scale: 1 },
+      layers: [
+        {
+          itemType: 'generation-dialog',
+          layerId: 'generation-dialog:generation-dialog-4',
+          resourceId: 'generation-dialog:generation-dialog-4',
+          dialog: {
+            id: 'generation-dialog-4',
+            mode: 'character',
+            prompt: '挥舞武器',
+            status: 'generating',
+            composerOpen: false,
+            imageModel: 'gpt-image-2',
+            placeholder: {
+              x: 2851,
+              y: -521,
+              width: 1024,
+              height: 1024,
+              originalWidth: 1024,
+              originalHeight: 1024,
+            },
+          },
+        },
+      ],
+      resources: [
+        {
+          resourceId: 'editor-resource-character',
+          projectId: 'editor-project-default',
+          imageSrc: '/api/assets/read-url?objectKey=character.png',
+          objectKey:
+            'generated-character-drafts/editor/character-images/vector-engine-edit/image.png',
+          assetObjectId: 'asset-object-character',
+          width: 1254,
+          height: 1254,
+          sourceType: 'generated',
+          prompt: '挥舞武器',
+          actualPrompt: '挥舞武器',
+          model: 'gpt-image-2',
+          provider: 'VectorEngine',
+          taskId: 'vector-engine-edit-1',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '挥舞武器' }],
+            references: [],
+          },
+          updatedAt: '2026-06-21T12:16:22.000Z',
+        },
+      ],
+      updatedAt: '2026-06-21T12:15:00.000Z',
+    });
+
+    render(<ProjectPersistenceHarness />);
+
+    expect(await screen.findByText('editor-project-default')).toBeTruthy();
+    expect(screen.getByTestId('layers').textContent).toBe('');
+    expect(screen.getByTestId('generation-dialogs').textContent).toBe(
+      'generation-dialog-4:挥舞武器:2851',
+    );
+    expect(saveEditorProjectLayoutMock).not.toHaveBeenCalled();
+  });
+
+  it('does not load protected project data before login is available', () => {
+    render(<ProjectPersistenceHarness canAccessProtectedData={false} />);
+
+    expect(loadOrCreateRecentEditorProjectMock).not.toHaveBeenCalled();
+    expect(loadEditorProjectMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('project-id').textContent).toBe('-');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasProjectPersistence.ts b/src/components/image-editor/useImageCanvasProjectPersistence.ts
new file mode 100644
index 000000000..a132588dc
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasProjectPersistence.ts
@@ -0,0 +1,350 @@
+import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
+
+import { ApiClientError } from '../../services/apiClient';
+import {
+  createEditorProjectResource,
+  loadEditorProject,
+  loadOrCreateRecentEditorProject,
+  saveEditorProjectLayout,
+  type EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import {
+  type CanvasLayerResourceMetadata,
+  hydrateLayer,
+  serializeCanvasLayout,
+  splitCanvasLayoutItems,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+} from './ImageCanvasEditorTypes';
+
+type ProjectResourceOptions = {
+  onCreated?: (resourceId: string) => void;
+  snapshotLayers?: CanvasLayer[];
+};
+
+type PendingProjectResourceLayer = {
+  layer: CanvasLayer;
+  options: ProjectResourceOptions;
+};
+
+type ImageCanvasProjectPersistenceRefs = {
+  layersRef: RefObject<CanvasLayer[]>;
+  viewportRef: RefObject<CanvasViewport>;
+  canvasGenerationDialogsRef: RefObject<CanvasGenerationDialogState[]>;
+};
+
+type ImageCanvasProjectPersistenceSetters = {
+  setProjectTitle: (title: string) => void;
+  setProjectRenameValue: (title: string) => void;
+  setViewport: (viewport: CanvasViewport) => void;
+  setLayers: (layers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  setLayerCounter: (value: number) => void;
+  restoreCanvasGenerationDialogs: (
+    dialogs: CanvasGenerationDialogState[],
+  ) => void;
+};
+
+function isEditorAuthError(error: unknown) {
+  return (
+    error instanceof ApiClientError &&
+    (error.status === 401 || error.status === 403)
+  );
+}
+
+function isLocalProjectResourceId(resourceId: string) {
+  return resourceId.startsWith('local-');
+}
+
+function resolveProjectResourceCreateImageSrc(layer: CanvasLayer) {
+  const objectKey = layer.objectKey?.trim();
+  if (objectKey) {
+    return `/${objectKey.replace(/^\/+/u, '')}`;
+  }
+  return layer.src;
+}
+
+export function useImageCanvasProjectPersistence({
+  refs,
+  setters,
+  layers,
+  canvasGenerationDialogs,
+  viewport,
+  canAccessProtectedData,
+  openEditorLoginModal,
+}: {
+  refs: ImageCanvasProjectPersistenceRefs;
+  setters: ImageCanvasProjectPersistenceSetters;
+  layers: CanvasLayer[];
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  viewport: CanvasViewport;
+  canAccessProtectedData: boolean;
+  openEditorLoginModal: (postLoginAction?: (() => void) | null) => void;
+}) {
+  const projectIdRef = useRef<string | null>(null);
+  const pendingProjectResourceLayersRef = useRef<PendingProjectResourceLayer[]>(
+    [],
+  );
+  const saveTimerRef = useRef<number | null>(null);
+  const [projectId, setProjectId] = useState<string | null>(null);
+  const [isProjectReady, setIsProjectReady] = useState(false);
+  const {
+    setProjectTitle,
+    setProjectRenameValue,
+    setViewport,
+    setLayers,
+    selectSingleLayer,
+    setLayerCounter,
+    restoreCanvasGenerationDialogs,
+  } = setters;
+
+  const createProjectResourceForLayer = useCallback(
+    (layer: CanvasLayer, options: ProjectResourceOptions = {}) => {
+      const readyProjectId = projectIdRef.current;
+      if (!readyProjectId) {
+        pendingProjectResourceLayersRef.current.push({ layer, options });
+        return;
+      }
+      createEditorProjectResource(readyProjectId, {
+        imageSrc: resolveProjectResourceCreateImageSrc(layer),
+        objectKey: layer.objectKey,
+        assetObjectId: layer.assetObjectId,
+        width: layer.originalWidth,
+        height: layer.originalHeight,
+        sourceType: layer.sourceType,
+        prompt: layer.prompt,
+        actualPrompt: layer.actualPrompt,
+        model: layer.model,
+        provider: layer.provider,
+        taskId: layer.taskId,
+        durationSeconds: layer.durationSeconds,
+        sourceResourceId: layer.sourceResourceId,
+        assetKind: layer.assetKind,
+        generationInputs: layer.generationInputs,
+      })
+        .then((resource) => {
+          options.onCreated?.(resource.resourceId);
+          const layerWithResourceId = {
+            ...layer,
+            resourceId: resource.resourceId,
+          };
+          const currentLayers = refs.layersRef.current;
+          const nextLayers = currentLayers.some(
+            (currentLayer) => currentLayer.id === layer.id,
+          )
+            ? currentLayers.map((currentLayer) =>
+                currentLayer.id === layer.id
+                  ? layerWithResourceId
+                  : currentLayer,
+              )
+            : options.snapshotLayers?.some(
+                  (snapshotLayer) => snapshotLayer.id === layer.id,
+                )
+              ? options.snapshotLayers.map((snapshotLayer) =>
+                  snapshotLayer.id === layer.id
+                    ? layerWithResourceId
+                    : snapshotLayer,
+                )
+              : currentLayers;
+          refs.layersRef.current = nextLayers;
+          setLayers(nextLayers);
+          if (nextLayers.length) {
+            void saveEditorProjectLayout(readyProjectId, {
+              viewport: refs.viewportRef.current,
+              layers: serializeCanvasLayout({
+                layers: nextLayers,
+                canvasGenerationDialogs:
+                  refs.canvasGenerationDialogsRef.current,
+              }),
+            }).catch((error: unknown) => {
+              if (isEditorAuthError(error)) {
+                openEditorLoginModal();
+              }
+            });
+          }
+        })
+        .catch((error: unknown) => {
+          if (isEditorAuthError(error)) {
+            openEditorLoginModal();
+          }
+        });
+    },
+    [openEditorLoginModal, refs, setLayers],
+  );
+
+  const applyProjectSnapshot = useCallback(
+    (project: EditorProjectSnapshot) => {
+      projectIdRef.current = project.projectId;
+      setProjectId(project.projectId);
+      const nextProjectTitle = project.title?.trim() || '未命名画布';
+      setProjectTitle(nextProjectTitle);
+      setProjectRenameValue(nextProjectTitle);
+      setViewport(project.viewport);
+      refs.viewportRef.current = project.viewport;
+      const resourcesById = new Map<string, CanvasLayerResourceMetadata>(
+        project.resources.map((resource) => [
+          resource.resourceId,
+          {
+            imageSrc: resource.imageSrc,
+            resourceId: resource.resourceId,
+            objectKey: resource.objectKey,
+            assetObjectId: resource.assetObjectId,
+            width: resource.width,
+            height: resource.height,
+            sourceType: resource.sourceType,
+            prompt: resource.prompt,
+            actualPrompt: resource.actualPrompt,
+            model: resource.model,
+            provider: resource.provider,
+            taskId: resource.taskId,
+            durationSeconds: resource.durationSeconds,
+            sourceResourceId: resource.sourceResourceId,
+            assetKind: resource.assetKind,
+            generationInputs: resource.generationInputs,
+            createdAt: resource.createdAt,
+            updatedAt: resource.updatedAt,
+          },
+        ]),
+      );
+      const { layerItems, generationDialogs } = splitCanvasLayoutItems(
+        project.layers,
+        resourcesById,
+      );
+      const hydratedLayers = layerItems
+        .map((layer) => hydrateLayer(layer, resourcesById))
+        .filter((layer): layer is CanvasLayer => Boolean(layer));
+      setLayerCounter(hydratedLayers.length);
+      refs.layersRef.current = hydratedLayers;
+      setLayers(hydratedLayers);
+      selectSingleLayer(hydratedLayers[0]?.id ?? null);
+      refs.canvasGenerationDialogsRef.current = generationDialogs;
+      restoreCanvasGenerationDialogs(generationDialogs);
+    },
+    [
+      refs,
+      restoreCanvasGenerationDialogs,
+      selectSingleLayer,
+      setLayerCounter,
+      setLayers,
+      setProjectRenameValue,
+      setProjectTitle,
+      setViewport,
+    ],
+  );
+
+  const appendCanvasLayersWithResources = useCallback(
+    (nextLayers: CanvasLayer[]) => {
+      if (!nextLayers.length) {
+        return;
+      }
+      const snapshotLayers = [...refs.layersRef.current, ...nextLayers];
+      refs.layersRef.current = snapshotLayers;
+      setLayers(snapshotLayers);
+      nextLayers.forEach((layer) =>
+        isLocalProjectResourceId(layer.resourceId)
+          ? createProjectResourceForLayer(layer, { snapshotLayers })
+          : undefined,
+      );
+    },
+    [createProjectResourceForLayer, refs, setLayers],
+  );
+
+  useEffect(() => {
+    if (!canAccessProtectedData) {
+      setIsProjectReady(false);
+      return undefined;
+    }
+    let cancelled = false;
+    const projectIdFromQuery =
+      typeof window === 'undefined'
+        ? null
+        : new URLSearchParams(window.location.search)
+            .get('projectid')
+            ?.trim() || null;
+    const loadProject = projectIdFromQuery
+      ? loadEditorProject(projectIdFromQuery)
+      : loadOrCreateRecentEditorProject();
+
+    loadProject
+      .then((project) => {
+        if (cancelled) {
+          return;
+        }
+        applyProjectSnapshot(project);
+        const pendingLayers = pendingProjectResourceLayersRef.current.splice(0);
+        pendingLayers.forEach(({ layer, options }) => {
+          createProjectResourceForLayer(layer, options);
+        });
+        setIsProjectReady(true);
+      })
+      .catch((error: unknown) => {
+        if (cancelled) {
+          return;
+        }
+        setIsProjectReady(false);
+        if (isEditorAuthError(error)) {
+          openEditorLoginModal(() => {
+            window.location.reload();
+          });
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    canAccessProtectedData,
+    applyProjectSnapshot,
+    createProjectResourceForLayer,
+    openEditorLoginModal,
+  ]);
+
+  useEffect(() => {
+    if (!projectId || !isProjectReady) {
+      return undefined;
+    }
+    if (saveTimerRef.current) {
+      window.clearTimeout(saveTimerRef.current);
+    }
+
+    saveTimerRef.current = window.setTimeout(() => {
+      saveEditorProjectLayout(projectId, {
+        viewport,
+        layers: serializeCanvasLayout({
+          layers,
+          canvasGenerationDialogs,
+        }),
+      }).catch((error: unknown) => {
+        if (isEditorAuthError(error)) {
+          openEditorLoginModal();
+        }
+      });
+    }, 450);
+
+    return () => {
+      if (saveTimerRef.current) {
+        window.clearTimeout(saveTimerRef.current);
+      }
+    };
+  }, [
+    isProjectReady,
+    canvasGenerationDialogs,
+    layers,
+    openEditorLoginModal,
+    projectId,
+    refs,
+    viewport,
+  ]);
+
+  return {
+    projectId,
+    isProjectReady,
+    projectIdRef,
+    createProjectResourceForLayer,
+    appendCanvasLayersWithResources,
+    applyProjectSnapshot,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasStageController.test.tsx b/src/components/image-editor/useImageCanvasStageController.test.tsx
new file mode 100644
index 000000000..546de2f88
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasStageController.test.tsx
@@ -0,0 +1,151 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasContextMenuState,
+  CanvasLayer,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasStageController } from './useImageCanvasStageController';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 80,
+    width: 240,
+    height: 120,
+    originalWidth: 240,
+    originalHeight: 120,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function StageControllerHarness({
+  hideGeneratedLayerPanelAfterBlur = vi.fn(),
+}: {
+  hideGeneratedLayerPanelAfterBlur?: () => void;
+}) {
+  const layers = [
+    createLayer({ id: 'first', hidden: true }),
+    createLayer({ id: 'second', locked: true }),
+  ];
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>('first');
+  const [selectedLayerIds, setSelectedLayerIds] = useState(['first', 'second']);
+  const [contextMenu, setContextMenu] =
+    useState<CanvasContextMenuState | null>(null);
+  const [imageContextMenu, setImageContextMenu] =
+    useState<ImageContextMenuState | null>({ layerId: 'first', x: 1, y: 2 });
+  const selectSingleLayer = (layerId: string | null) => {
+    setSelectedLayerId(layerId);
+    setSelectedLayerIds(layerId ? [layerId] : []);
+  };
+  const controller = useImageCanvasStageController({
+    layers,
+    selectedLayerId,
+    selectedLayerIds,
+    imageContextMenu,
+    setImageContextMenu,
+    contextMenu,
+    setContextMenu,
+    viewport: { x: 0, y: 0, scale: 1 },
+    canvasSize: { width: 900, height: 640 },
+    selectSingleLayer,
+    hideGeneratedLayerPanelAfterBlur,
+    getCanvasPointFromClient: (clientX, clientY) => ({
+      x: clientX + 1,
+      y: clientY + 2,
+    }),
+  });
+
+  return (
+    <div>
+      <span data-testid="selected">
+        {selectedLayerId ?? '-'}:{selectedLayerIds.join(',')}
+      </span>
+      <span data-testid="context">
+        {contextMenu
+          ? `${contextMenu.kind}:${contextMenu.x}:${contextMenu.y}:${contextMenu.canvasPoint.x}:${contextMenu.canvasPoint.y}`
+          : '-'}
+      </span>
+      <span data-testid="image-context">
+        {imageContextMenu
+          ? `${imageContextMenu.layerId}:${imageContextMenu.x}:${imageContextMenu.y}`
+          : '-'}
+      </span>
+      <span data-testid="show-layer">
+        {String(controller.contextShouldShowLayer)}
+      </span>
+      <span data-testid="unlock-layer">
+        {String(controller.contextShouldUnlockLayer)}
+      </span>
+      <button type="button" onClick={controller.clearCanvasFocus}>
+        清空焦点
+      </button>
+      <div
+        role="presentation"
+        data-testid="canvas"
+        onContextMenu={controller.handleCanvasContextMenu}
+      />
+      <button
+        type="button"
+        onContextMenu={(event) =>
+          controller.handleLayerContextMenu(event, layers[1]!)
+        }
+      >
+        图层右键目标
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasStageController', () => {
+  it('clears canvas focus and closes generated layer panels', () => {
+    const hideGeneratedLayerPanelAfterBlur = vi.fn();
+    render(
+      <StageControllerHarness
+        hideGeneratedLayerPanelAfterBlur={hideGeneratedLayerPanelAfterBlur}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '清空焦点' }));
+
+    expect(screen.getByTestId('selected').textContent).toBe('-:');
+    expect(screen.getByTestId('image-context').textContent).toBe('-');
+    expect(screen.getByTestId('context').textContent).toBe('-');
+    expect(hideGeneratedLayerPanelAfterBlur).toHaveBeenCalledTimes(1);
+  });
+
+  it('creates blank and layer context menus and preserves multi-target state', () => {
+    render(<StageControllerHarness />);
+
+    fireEvent.contextMenu(screen.getByTestId('canvas'), {
+      clientX: 20,
+      clientY: 30,
+    });
+    expect(screen.getByTestId('context').textContent).toBe('blank:20:30:21:32');
+    expect(screen.getByTestId('image-context').textContent).toBe('-');
+
+    fireEvent.contextMenu(
+      screen.getByRole('button', { name: '图层右键目标' }),
+      {
+        clientX: 40,
+        clientY: 50,
+      },
+    );
+    expect(screen.getByTestId('context').textContent).toBe('layer:40:50:41:52');
+    expect(screen.getByTestId('image-context').textContent).toBe('second:40:50');
+    expect(screen.getByTestId('show-layer').textContent).toBe('true');
+    expect(screen.getByTestId('unlock-layer').textContent).toBe('true');
+  });
+
+});
diff --git a/src/components/image-editor/useImageCanvasStageController.ts b/src/components/image-editor/useImageCanvasStageController.ts
new file mode 100644
index 000000000..92fbc291c
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasStageController.ts
@@ -0,0 +1,143 @@
+import {
+  type Dispatch,
+  type MouseEvent as ReactMouseEvent,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+} from 'react';
+
+import type {
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+import {
+  createBlankCanvasContextMenu,
+  createLayerCanvasContextMenus,
+  resolveImageCanvasStageControllerModel,
+} from './ImageCanvasStageControllerModel';
+
+type UseImageCanvasStageControllerOptions = {
+  layers: CanvasLayer[];
+  canvasGenerationDialogs?: CanvasGenerationDialogState[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  imageContextMenu: ImageContextMenuState | null;
+  setImageContextMenu: Dispatch<SetStateAction<ImageContextMenuState | null>>;
+  contextMenu: CanvasContextMenuState | null;
+  setContextMenu: Dispatch<SetStateAction<CanvasContextMenuState | null>>;
+  viewport: CanvasViewport;
+  canvasSize: { width: number; height: number };
+  selectSingleLayer: (layerId: string | null) => void;
+  hideGeneratedLayerPanelAfterBlur: () => void;
+  clearGenerationPanelsAfterBlur?: () => void;
+  getCanvasPointFromClient: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number };
+};
+
+export function useImageCanvasStageController({
+  layers,
+  canvasGenerationDialogs,
+  selectedLayerId,
+  selectedLayerIds,
+  imageContextMenu,
+  setImageContextMenu,
+  contextMenu,
+  setContextMenu,
+  viewport,
+  canvasSize,
+  selectSingleLayer,
+  hideGeneratedLayerPanelAfterBlur,
+  clearGenerationPanelsAfterBlur,
+  getCanvasPointFromClient,
+}: UseImageCanvasStageControllerOptions) {
+  const model = useMemo(
+    () =>
+      resolveImageCanvasStageControllerModel({
+        layers,
+        canvasGenerationDialogs,
+        selectedLayerId,
+        selectedLayerIds,
+        imageContextMenu,
+        contextMenu,
+        viewport,
+        canvasSize,
+      }),
+    [
+      canvasSize,
+      canvasGenerationDialogs,
+      contextMenu,
+      imageContextMenu,
+      layers,
+      selectedLayerId,
+      selectedLayerIds,
+      viewport,
+    ],
+  );
+
+  const clearCanvasFocus = useCallback(() => {
+    selectSingleLayer(null);
+    hideGeneratedLayerPanelAfterBlur();
+    clearGenerationPanelsAfterBlur?.();
+    setImageContextMenu(null);
+    setContextMenu(null);
+  }, [
+    clearGenerationPanelsAfterBlur,
+    hideGeneratedLayerPanelAfterBlur,
+    selectSingleLayer,
+    setContextMenu,
+    setImageContextMenu,
+  ]);
+
+  const handleCanvasContextMenu = useCallback(
+    (event: ReactMouseEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+      setImageContextMenu(null);
+      setContextMenu(
+        createBlankCanvasContextMenu({
+          clientX: event.clientX,
+          clientY: event.clientY,
+          canvasPoint: getCanvasPointFromClient(event.clientX, event.clientY),
+        }),
+      );
+    },
+    [getCanvasPointFromClient, setContextMenu, setImageContextMenu],
+  );
+
+  const handleLayerContextMenu = useCallback(
+    (event: ReactMouseEvent<HTMLElement>, layer: CanvasLayer) => {
+      event.preventDefault();
+      event.stopPropagation();
+      if (!selectedLayerIds.includes(layer.id)) {
+        selectSingleLayer(layer.id);
+      }
+      const nextMenus = createLayerCanvasContextMenus({
+        clientX: event.clientX,
+        clientY: event.clientY,
+        layerId: layer.id,
+        canvasPoint: getCanvasPointFromClient(event.clientX, event.clientY),
+      });
+      setContextMenu(nextMenus.contextMenu);
+      setImageContextMenu(nextMenus.imageContextMenu);
+    },
+    [
+      getCanvasPointFromClient,
+      selectSingleLayer,
+      selectedLayerIds,
+      setContextMenu,
+      setImageContextMenu,
+    ],
+  );
+
+  return {
+    ...model,
+    clearCanvasFocus,
+    handleCanvasContextMenu,
+    handleLayerContextMenu,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasStageInteractions.test.tsx b/src/components/image-editor/useImageCanvasStageInteractions.test.tsx
new file mode 100644
index 000000000..8fe34a582
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasStageInteractions.test.tsx
@@ -0,0 +1,766 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import {
+  type PointerEvent as ReactPointerEvent,
+  useRef,
+  useState,
+} from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  GenerateDialogState,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasStageInteractions } from './useImageCanvasStageInteractions';
+import { getCanvasGenerationSelectionId } from './ImageCanvasSelectionModel';
+
+function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 100,
+    width: 100,
+    height: 80,
+    originalWidth: 100,
+    originalHeight: 80,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function setElementBox(
+  element: HTMLElement,
+  box: { width: number; height: number; left?: number; top?: number },
+) {
+  Object.defineProperty(element, 'clientWidth', {
+    configurable: true,
+    value: box.width,
+  });
+  Object.defineProperty(element, 'clientHeight', {
+    configurable: true,
+    value: box.height,
+  });
+  element.getBoundingClientRect = () =>
+    ({
+      x: box.left ?? 0,
+      y: box.top ?? 0,
+      left: box.left ?? 0,
+      top: box.top ?? 0,
+      right: (box.left ?? 0) + box.width,
+      bottom: (box.top ?? 0) + box.height,
+      width: box.width,
+      height: box.height,
+      toJSON: () => ({}),
+    }) as DOMRect;
+  element.setPointerCapture = vi.fn();
+  element.releasePointerCapture = vi.fn();
+  element.hasPointerCapture = vi.fn(() => true);
+}
+
+function createPointerEvent<TElement extends HTMLElement>(
+  currentTarget: TElement,
+  options: {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    button?: number;
+    buttons?: number;
+    shiftKey?: boolean;
+    target?: EventTarget;
+  },
+): ReactPointerEvent<TElement> {
+  return {
+    preventDefault: vi.fn(),
+    stopPropagation: vi.fn(),
+    currentTarget,
+    target: options.target ?? currentTarget,
+    pointerId: options.pointerId,
+    clientX: options.clientX,
+    clientY: options.clientY,
+    button: options.button ?? 0,
+    buttons: options.buttons ?? 1,
+    shiftKey: options.shiftKey ?? false,
+    nativeEvent: {
+      pointerId: options.pointerId,
+      clientX: options.clientX,
+      clientY: options.clientY,
+      button: options.button ?? 0,
+      buttons: options.buttons ?? 1,
+    },
+  } as unknown as ReactPointerEvent<TElement>;
+}
+
+function asCanvasGenerationDialog(
+  dialog: GenerateDialogState | null,
+): CanvasGenerationDialogState | null {
+  if (!dialog?.id || dialog.mode === 'edit') {
+    return null;
+  }
+  return dialog as CanvasGenerationDialogState;
+}
+
+function StageInteractionsHarness({
+  pickCharacterSpecFromLayer = vi.fn(),
+  pickGenerationReferenceFromLayer = vi.fn(),
+  pickIconSpecFromLayer = vi.fn(),
+  isPickingGenerationReferenceFromCanvas = false,
+  activateCanvasGenerationDialog = vi.fn(),
+  moveViewportFromMinimapPointer = vi.fn(),
+  updateViewportFromMinimapDrag = vi.fn(),
+}: {
+  pickCharacterSpecFromLayer?: (layer: CanvasLayer) => void;
+  pickGenerationReferenceFromLayer?: (layer: CanvasLayer) => void;
+  pickIconSpecFromLayer?: (layer: CanvasLayer) => void;
+  isPickingGenerationReferenceFromCanvas?: boolean;
+  activateCanvasGenerationDialog?: (
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  moveViewportFromMinimapPointer?: (clientX: number, clientY: number) => void;
+  updateViewportFromMinimapDrag?: (
+    dragState: {
+      kind: 'minimap';
+      pointerId: number;
+      moved: boolean;
+    },
+    clientX: number,
+    clientY: number,
+  ) => void;
+}) {
+  const canvasViewportRef = useRef<HTMLDivElement | null>(null);
+  const worldRef = useRef<HTMLDivElement | null>(null);
+  const [activeTool, setActiveTool] = useState<'select' | 'hand'>('select');
+  const [layers, setLayers] = useState<CanvasLayer[]>([
+    createLayer({ id: 'first', x: 40, y: 40, zIndex: 1 }),
+    createLayer({ id: 'second', x: 220, y: 60, zIndex: 2 }),
+  ]);
+  const [viewport, setViewport] = useState<CanvasViewport>({
+    x: 0,
+    y: 0,
+    scale: 1,
+  });
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
+  const [selectedLayerIds, setSelectedLayerIds] = useState<string[]>([]);
+  const [generateDialog, setGenerateDialog] =
+    useState<GenerateDialogState | null>({
+      id: 'dialog-1',
+      mode: 'generate',
+      prompt: '生成',
+      status: 'idle',
+      composerOpen: true,
+      placeholder: {
+        x: 300,
+        y: 200,
+        width: 160,
+        height: 120,
+        originalWidth: 160,
+        originalHeight: 120,
+      },
+    });
+  const activeGenerationDialog = asCanvasGenerationDialog(generateDialog);
+  const canvasGenerationDialogs = activeGenerationDialog
+    ? [activeGenerationDialog]
+    : [];
+  const [clearCount, setClearCount] = useState(0);
+  const [imageMenuCloseCount, setImageMenuCloseCount] = useState(0);
+
+  const interaction = useImageCanvasStageInteractions({
+    canvasViewportRef,
+    activeTool,
+    layers,
+    setLayers,
+    viewport,
+    setViewport,
+    selectedLayerIds,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+    generateDialog,
+    canvasGenerationDialogs,
+    setGenerateDialog,
+    isPickingCharacterSpecFromCanvas: false,
+    isPickingGenerationReferenceFromCanvas,
+    isPickingQuickEditReferenceFromCanvas: false,
+    isPickingCharacterReferenceFromCanvas: false,
+    isPickingIconSpecFromCanvas: false,
+    isPickingUiDesignSpecFromCanvas: false,
+    isPickingPublicationReferenceFromCanvas: false,
+    clearCanvasFocus: () => {
+      setSelectedLayerId(null);
+      setSelectedLayerIds([]);
+      setClearCount((currentCount) => currentCount + 1);
+    },
+    pickCharacterSpecFromLayer,
+    pickGenerationReferenceFromLayer,
+    pickQuickEditReferenceFromLayer: vi.fn(),
+    pickCharacterReferenceFromLayer: vi.fn(),
+    pickIconSpecFromLayer,
+    pickUiDesignSpecFromLayer: vi.fn(),
+    pickPublicationReferenceFromLayer: vi.fn(),
+    activateCanvasGenerationDialog,
+    updateCanvasGenerationDialogById: (dialogId, updater) => {
+      setGenerateDialog((currentDialog) => {
+        if (
+          !currentDialog?.id ||
+          currentDialog?.id !== dialogId ||
+          currentDialog.mode === 'edit'
+        ) {
+          return currentDialog;
+        }
+        return updater(currentDialog as CanvasGenerationDialogState);
+      });
+    },
+    moveViewportFromMinimapPointer,
+    updateViewportFromMinimapDrag: (dragState, clientX, clientY) =>
+      updateViewportFromMinimapDrag(
+        {
+          kind: dragState.kind,
+          pointerId: dragState.pointerId,
+          moved: dragState.moved,
+        },
+        clientX,
+        clientY,
+      ),
+    minimapScale: 0.5,
+    onCloseImageContextMenu: () =>
+      setImageMenuCloseCount((currentCount) => currentCount + 1),
+  });
+  const getViewportElement = () => {
+    const element = canvasViewportRef.current;
+    if (!element) {
+      throw new Error('canvas viewport is not ready');
+    }
+    return element;
+  };
+  const firstLayer = layers[0];
+  const secondLayer = layers[1];
+  if (!firstLayer || !secondLayer) {
+    throw new Error('stage interaction test layers are not ready');
+  }
+
+  return (
+    <div>
+      <div
+        ref={(element) => {
+          canvasViewportRef.current = element;
+          if (element) {
+            setElementBox(element, { width: 640, height: 480 });
+          }
+        }}
+        data-testid="viewport"
+        onPointerDown={interaction.handleCanvasPointerDown}
+        onPointerMove={interaction.handlePointerMove}
+        onPointerUp={interaction.finishDrag}
+      >
+        <div
+          ref={worldRef}
+          className="image-canvas-editor__world"
+          data-testid="world"
+        />
+        {layers.map((layer) => (
+          <button
+            key={layer.id}
+            type="button"
+            data-testid={`layer-${layer.id}`}
+            onClick={(event) => interaction.handleLayerClick(event, layer)}
+            onPointerDown={(event) =>
+              interaction.handleLayerPointerDown(event, layer)
+            }
+          >
+            {layer.id}
+          </button>
+        ))}
+        {activeGenerationDialog?.placeholder ? (
+          <div
+            data-testid="generation-frame"
+            onPointerDown={(event) =>
+              interaction.handleGenerationFramePointerDown(
+                event,
+                activeGenerationDialog,
+              )
+            }
+          />
+        ) : null}
+        <button
+          type="button"
+          data-testid="minimap"
+          onPointerDown={interaction.handleMinimapPointerDown}
+        >
+          小地图
+        </button>
+      </div>
+      <span data-testid="selection">
+        {selectedLayerId ?? '-'}:{selectedLayerIds.join(',')}
+      </span>
+      <span data-testid="layers">
+        {layers
+          .map((layer) => `${layer.id}:${layer.x.toFixed(1)},${layer.y.toFixed(1)}`)
+          .join('|')}
+      </span>
+      <span data-testid="viewport-state">
+        {viewport.x.toFixed(1)},{viewport.y.toFixed(1)},{viewport.scale}
+      </span>
+      <span data-testid="marquee">
+        {interaction.canvasMarquee
+          ? `${interaction.canvasMarquee.startX},${interaction.canvasMarquee.currentX}`
+          : '-'}
+      </span>
+      <span data-testid="panning">{String(interaction.isPanning)}</span>
+      <span data-testid="tool">{interaction.effectiveTool}</span>
+      <span data-testid="snap">
+        {interaction.snapGuide?.vertical ?? interaction.snapGuide?.horizontal ?? '-'}
+      </span>
+      <span data-testid="dialog-position">
+        {generateDialog?.placeholder
+          ? `${generateDialog.placeholder.x.toFixed(1)},${generateDialog.placeholder.y.toFixed(1)}`
+          : '-'}
+      </span>
+      <span data-testid="dialog-selection-id">
+        {getCanvasGenerationSelectionId('dialog-1')}
+      </span>
+      <span data-testid="dialog-open">
+        {String(generateDialog?.composerOpen ?? false)}
+      </span>
+      <span data-testid="clear-count">{clearCount}</span>
+      <span data-testid="image-menu-close-count">
+        {imageMenuCloseCount}
+      </span>
+      <button
+        type="button"
+        onClick={() => {
+          interaction.setShiftPressed(true);
+        }}
+      >
+        按住 Shift
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          interaction.setIsSpacePanning(true);
+        }}
+      >
+        按住空格
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          interaction.setIsSpacePanning(false);
+        }}
+      >
+        松开空格
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          interaction.clearActiveInteraction();
+        }}
+      >
+        清理交互
+      </button>
+      <button type="button" onClick={() => setActiveTool('hand')}>
+        切抓手
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleLayerPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 1,
+              clientX: 40,
+              clientY: 40,
+            }),
+            firstLayer,
+          );
+          interaction.setShiftPressed(false);
+        }}
+      >
+        直接选第一层
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.setShiftPressed(true);
+          interaction.handleLayerPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 2,
+              clientX: 220,
+              clientY: 60,
+            }),
+            secondLayer,
+          );
+        }}
+      >
+        直接追加第二层
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 2,
+              clientX: 250,
+              clientY: 90,
+            }),
+          );
+        }}
+      >
+        直接移动图层
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.finishDrag(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 2,
+              clientX: 250,
+              clientY: 90,
+            }),
+          );
+        }}
+      >
+        直接结束图层拖拽
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleCanvasPointerDown(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 3,
+              clientX: 20,
+              clientY: 20,
+              target: worldRef.current ?? undefined,
+            }),
+          );
+        }}
+      >
+        直接开始框选
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 3,
+              clientX: 190,
+              clientY: 150,
+            }),
+          );
+        }}
+      >
+        直接移动框选
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.finishDrag(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 3,
+              clientX: 190,
+              clientY: 150,
+            }),
+          );
+        }}
+      >
+        直接结束框选
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleCanvasPointerDown(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 4,
+              clientX: 100,
+              clientY: 100,
+            }),
+          );
+        }}
+      >
+        直接开始平移
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 4,
+              clientX: 130,
+              clientY: 125,
+            }),
+          );
+        }}
+      >
+        直接移动平移
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          const frameElement = document.createElement('div');
+          const dialog = asCanvasGenerationDialog(generateDialog);
+          if (!dialog) {
+            return;
+          }
+          interaction.handleGenerationFramePointerDown(
+            createPointerEvent(frameElement, {
+              pointerId: 5,
+              clientX: 300,
+              clientY: 200,
+            }),
+            dialog,
+          );
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 5,
+              clientX: 340,
+              clientY: 230,
+            }),
+          );
+        }}
+      >
+        直接拖生成占位
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          const frameElement = document.createElement('div');
+          const dialog = asCanvasGenerationDialog(generateDialog);
+          if (!dialog) {
+            return;
+          }
+          interaction.handleGenerationFramePointerDown(
+            createPointerEvent(frameElement, {
+              pointerId: 9,
+              clientX: 300,
+              clientY: 200,
+            }),
+            dialog,
+          );
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 9,
+              clientX: 220,
+              clientY: 60,
+            }),
+          );
+        }}
+      >
+        直接贴近图层拖生成占位
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          const frameElement = document.createElement('div');
+          const dialog = asCanvasGenerationDialog(generateDialog);
+          if (!dialog) {
+            return;
+          }
+          interaction.setShiftPressed(true);
+          interaction.handleGenerationFramePointerDown(
+            createPointerEvent(frameElement, {
+              pointerId: 8,
+              clientX: 300,
+              clientY: 200,
+            }),
+            dialog,
+          );
+        }}
+      >
+        直接追加生成器
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleMinimapPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 6,
+              clientX: 120,
+              clientY: 90,
+            }),
+          );
+          interaction.finishDrag(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 6,
+              clientX: 120,
+              clientY: 90,
+            }),
+          );
+        }}
+      >
+        直接点击小地图
+      </button>
+      <button
+        type="button"
+        onClick={(event) => {
+          interaction.handleMinimapPointerDown(
+            createPointerEvent(event.currentTarget, {
+              pointerId: 7,
+              clientX: 120,
+              clientY: 90,
+            }),
+          );
+          interaction.handlePointerMove(
+            createPointerEvent(getViewportElement(), {
+              pointerId: 7,
+              clientX: 130,
+              clientY: 95,
+            }),
+          );
+        }}
+      >
+        直接拖小地图
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasStageInteractions', () => {
+  it('selects and drags multiple layers from stage pointer events', () => {
+    render(<StageInteractionsHarness />);
+
+    act(() => {
+      screen.getByRole('button', { name: '直接选第一层' }).click();
+    });
+    expect(screen.getByTestId('selection').textContent).toBe('first:first');
+    expect(screen.getByTestId('dialog-open').textContent).toBe('false');
+
+    act(() => {
+      screen.getByRole('button', { name: '直接追加第二层' }).click();
+    });
+    expect(screen.getByTestId('selection').textContent).toBe(
+      'second:first,second',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接移动图层' }).click();
+    });
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'first:70.0,70.0',
+    );
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'second:250.0,90.0',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接结束图层拖拽' }).click();
+    });
+    expect(screen.getByTestId('snap').textContent).toBe('-');
+  });
+
+  it('handles marquee, temporary hand mode, and generation frame dragging', () => {
+    const activateCanvasGenerationDialog = vi.fn();
+    render(
+      <StageInteractionsHarness
+        activateCanvasGenerationDialog={activateCanvasGenerationDialog}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接开始框选' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '直接移动框选' }).click();
+    });
+    expect(screen.getByTestId('selection').textContent).toBe('first:first');
+    expect(screen.getByTestId('marquee').textContent).toBe('20,190');
+
+    act(() => {
+      screen.getByRole('button', { name: '直接结束框选' }).click();
+    });
+    expect(screen.getByTestId('marquee').textContent).toBe('-');
+
+    act(() => {
+      screen.getByRole('button', { name: '按住空格' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '直接开始平移' }).click();
+    });
+    expect(screen.getByTestId('tool').textContent).toBe('hand');
+    expect(screen.getByTestId('panning').textContent).toBe('true');
+    act(() => {
+      screen.getByRole('button', { name: '直接移动平移' }).click();
+    });
+    expect(screen.getByTestId('viewport-state').textContent).toBe('30.0,25.0,1');
+
+    act(() => {
+      screen.getByRole('button', { name: '清理交互' }).click();
+      screen.getByRole('button', { name: '松开空格' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '直接拖生成占位' }).click();
+    });
+    expect(activateCanvasGenerationDialog).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId('dialog-position').textContent).toBe(
+      '340.0,230.0',
+    );
+  });
+
+  it('shows snap guides when generation frames drag near layer alignment', () => {
+    render(<StageInteractionsHarness />);
+
+    act(() => {
+      screen
+        .getByRole('button', { name: '直接贴近图层拖生成占位' })
+        .click();
+    });
+
+    expect(screen.getByTestId('dialog-position').textContent).toBe(
+      '220.0,60.0',
+    );
+    expect(screen.getByTestId('snap').textContent).toBe('220');
+  });
+
+  it('selects generation frames and keeps mixed selections movable', () => {
+    render(<StageInteractionsHarness />);
+
+    act(() => {
+      screen.getByRole('button', { name: '直接选第一层' }).click();
+    });
+    act(() => {
+      screen.getByRole('button', { name: '直接追加生成器' }).click();
+    });
+    expect(screen.getByTestId('selection').textContent).toBe(
+      `first:first,${screen.getByTestId('dialog-selection-id').textContent}`,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接拖生成占位' }).click();
+    });
+    expect(screen.getByTestId('dialog-position').textContent).toBe(
+      '340.0,230.0',
+    );
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'first:80.0,70.0',
+    );
+  });
+
+  it('distinguishes minimap click and drag movement', () => {
+    const moveViewportFromMinimapPointer = vi.fn();
+    const updateViewportFromMinimapDrag = vi.fn();
+    render(
+      <StageInteractionsHarness
+        moveViewportFromMinimapPointer={moveViewportFromMinimapPointer}
+        updateViewportFromMinimapDrag={updateViewportFromMinimapDrag}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '直接点击小地图' }).click();
+    });
+    expect(moveViewportFromMinimapPointer).toHaveBeenCalledWith(120, 90);
+    expect(updateViewportFromMinimapDrag).not.toHaveBeenCalled();
+
+    act(() => {
+      screen.getByRole('button', { name: '直接拖小地图' }).click();
+    });
+    expect(updateViewportFromMinimapDrag).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: 'minimap', pointerId: 7, moved: true }),
+      130,
+      95,
+    );
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasStageInteractions.ts b/src/components/image-editor/useImageCanvasStageInteractions.ts
new file mode 100644
index 000000000..2d9ead0c1
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasStageInteractions.ts
@@ -0,0 +1,647 @@
+import {
+  type Dispatch,
+  type PointerEvent as ReactPointerEvent,
+  type MouseEvent as ReactMouseEvent,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import {
+  moveGenerationFramesFromDrag,
+  moveDragSelectedLayers,
+  moveLayersFromDrag,
+  moveViewportFromPan,
+  selectCanvasObjectsInsideMarquee,
+} from './ImageCanvasInteractionModel';
+import {
+  createCanvasMarqueeState,
+  createGenerationFrameSelectionStart,
+  createLayerDragStart,
+  createMinimapDragState,
+  createPanDragState,
+  getCanvasPointFromPointer,
+  getPointerButton,
+  getPointerClient,
+  getPointerId,
+  updateGenerateDialogForLayerClick,
+  updateGenerateDialogForLayerPointerDown,
+  updateMinimapDragMovement,
+} from './ImageCanvasStageInteractionModel';
+import type {
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasMarqueeState,
+  CanvasTool,
+  CanvasViewport,
+  DragState,
+  GenerateDialogState,
+  SnapGuide,
+} from './ImageCanvasEditorTypes';
+
+type UseImageCanvasStageInteractionsOptions = {
+  canvasViewportRef: RefObject<HTMLDivElement | null>;
+  activeTool: CanvasTool;
+  layers: CanvasLayer[];
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  viewport: CanvasViewport;
+  setViewport: Dispatch<SetStateAction<CanvasViewport>>;
+  selectedLayerIds: string[];
+  setSelectedLayerId: Dispatch<SetStateAction<string | null>>;
+  setSelectedLayerIds: Dispatch<SetStateAction<string[]>>;
+  generateDialog: GenerateDialogState | null;
+  canvasGenerationDialogs: CanvasGenerationDialogState[];
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  isPickingCharacterSpecFromCanvas: boolean;
+  isPickingGenerationReferenceFromCanvas: boolean;
+  isPickingQuickEditReferenceFromCanvas: boolean;
+  isPickingCharacterReferenceFromCanvas: boolean;
+  isPickingIconSpecFromCanvas: boolean;
+  isPickingUiDesignSpecFromCanvas: boolean;
+  isPickingPublicationReferenceFromCanvas: boolean;
+  clearCanvasFocus: () => void;
+  pickCharacterSpecFromLayer: (layer: CanvasLayer) => void;
+  pickGenerationReferenceFromLayer: (layer: CanvasLayer) => void;
+  pickQuickEditReferenceFromLayer: (layer: CanvasLayer) => void;
+  pickCharacterReferenceFromLayer: (layer: CanvasLayer) => void;
+  pickIconSpecFromLayer: (layer: CanvasLayer) => void;
+  pickUiDesignSpecFromLayer: (layer: CanvasLayer) => void;
+  pickPublicationReferenceFromLayer: (layer: CanvasLayer) => void;
+  activateCanvasGenerationDialog: (
+    dialog: CanvasGenerationDialogState,
+  ) => void;
+  updateCanvasGenerationDialogById: (
+    dialogId: string,
+    updater: (
+      dialog: CanvasGenerationDialogState,
+    ) => CanvasGenerationDialogState | null,
+  ) => void;
+  moveViewportFromMinimapPointer: (clientX: number, clientY: number) => void;
+  updateViewportFromMinimapDrag: (
+    dragState: Extract<DragState, { kind: 'minimap' }>,
+    clientX: number,
+    clientY: number,
+  ) => void;
+  minimapScale: number;
+  onCloseImageContextMenu: () => void;
+};
+
+export function useImageCanvasStageInteractions({
+  canvasViewportRef,
+  activeTool,
+  layers,
+  setLayers,
+  viewport,
+  setViewport,
+  selectedLayerIds,
+  setSelectedLayerId,
+  setSelectedLayerIds,
+  generateDialog,
+  canvasGenerationDialogs,
+  setGenerateDialog,
+  isPickingCharacterSpecFromCanvas,
+  isPickingGenerationReferenceFromCanvas,
+  isPickingQuickEditReferenceFromCanvas,
+  isPickingCharacterReferenceFromCanvas,
+  isPickingIconSpecFromCanvas,
+  isPickingUiDesignSpecFromCanvas,
+  isPickingPublicationReferenceFromCanvas,
+  clearCanvasFocus,
+  pickCharacterSpecFromLayer,
+  pickGenerationReferenceFromLayer,
+  pickQuickEditReferenceFromLayer,
+  pickCharacterReferenceFromLayer,
+  pickIconSpecFromLayer,
+  pickUiDesignSpecFromLayer,
+  pickPublicationReferenceFromLayer,
+  activateCanvasGenerationDialog,
+  updateCanvasGenerationDialogById,
+  moveViewportFromMinimapPointer,
+  updateViewportFromMinimapDrag,
+  minimapScale,
+  onCloseImageContextMenu,
+}: UseImageCanvasStageInteractionsOptions) {
+  const dragStateRef = useRef<DragState | null>(null);
+  const isShiftPressedRef = useRef(false);
+  const suppressNextLayerClickRef = useRef(false);
+  const [canvasMarquee, setCanvasMarquee] = useState<CanvasMarqueeState | null>(
+    null,
+  );
+  const [isSpacePanning, setIsSpacePanning] = useState(false);
+  const [isPanning, setIsPanning] = useState(false);
+  const [snapGuide, setSnapGuide] = useState<SnapGuide | null>(null);
+  const effectiveTool: CanvasTool = isSpacePanning ? 'hand' : activeTool;
+
+  const clearActiveInteraction = useCallback(() => {
+    dragStateRef.current = null;
+    setCanvasMarquee(null);
+    setIsPanning(false);
+    setSnapGuide(null);
+  }, []);
+
+  const setShiftPressed = useCallback((pressed: boolean) => {
+    isShiftPressedRef.current = pressed;
+  }, []);
+
+  const startPan = useCallback(
+    (event: ReactPointerEvent<HTMLElement>) => {
+      event.preventDefault();
+      const pointer = getPointerClient(event);
+      canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
+      setIsPanning(true);
+      dragStateRef.current = createPanDragState({
+        pointerId: getPointerId(event),
+        pointer,
+        viewport,
+      });
+    },
+    [canvasViewportRef, viewport],
+  );
+
+  const handleCanvasPointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const button = getPointerButton(event);
+      if (button !== 0 || effectiveTool === 'hand') {
+        startPan(event);
+        return;
+      }
+
+      if (button !== 0) {
+        return;
+      }
+      const target = event.target as HTMLElement;
+      if (
+        effectiveTool === 'select' &&
+        (event.target === event.currentTarget ||
+          target.classList.contains('image-canvas-editor__world'))
+      ) {
+        event.preventDefault();
+        const rect = canvasViewportRef.current?.getBoundingClientRect();
+        const pointer = getPointerClient(event);
+        canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
+        setCanvasMarquee(
+          createCanvasMarqueeState({
+            pointerId: getPointerId(event),
+            pointer,
+            rect,
+          }),
+        );
+        clearCanvasFocus();
+        return;
+      }
+      clearCanvasFocus();
+    },
+    [canvasViewportRef, clearCanvasFocus, effectiveTool, startPan],
+  );
+
+  const handleLayerPointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLElement>, layer: CanvasLayer) => {
+      const button = getPointerButton(event);
+      if (button === 1 || effectiveTool === 'hand') {
+        event.stopPropagation();
+        startPan(event);
+        return;
+      }
+      if (button !== 0) {
+        event.stopPropagation();
+        return;
+      }
+      if (
+        isPickingGenerationReferenceFromCanvas &&
+        (generateDialog?.mode === 'generate' ||
+          generateDialog?.mode === 'video' ||
+          generateDialog?.mode === 'spec')
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickGenerationReferenceFromLayer(layer);
+        return;
+      }
+      if (isPickingQuickEditReferenceFromCanvas) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickQuickEditReferenceFromLayer(layer);
+        return;
+      }
+      if (
+        isPickingCharacterSpecFromCanvas &&
+        generateDialog?.mode === 'character'
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickCharacterSpecFromLayer(layer);
+        return;
+      }
+      if (
+        isPickingCharacterReferenceFromCanvas &&
+        generateDialog?.mode === 'character'
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickCharacterReferenceFromLayer(layer);
+        return;
+      }
+      if (isPickingIconSpecFromCanvas && generateDialog?.mode === 'icon') {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickIconSpecFromLayer(layer);
+        return;
+      }
+      if (
+        isPickingUiDesignSpecFromCanvas &&
+        generateDialog?.mode === 'ui-design'
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickUiDesignSpecFromLayer(layer);
+        return;
+      }
+      if (
+        isPickingPublicationReferenceFromCanvas &&
+        generateDialog?.mode === 'publication'
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextLayerClickRef.current = true;
+        pickPublicationReferenceFromLayer(layer);
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      const pointer = getPointerClient(event);
+      canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
+      const isMultiSelectGesture = event.shiftKey || isShiftPressedRef.current;
+      const layerDragStart = createLayerDragStart({
+        layer,
+        layers,
+        generationDialogs: canvasGenerationDialogs,
+        selectedLayerIds,
+        isMultiSelectGesture,
+        pointerId: getPointerId(event),
+        pointer,
+        viewportScale: viewport.scale,
+      });
+      setSelectedLayerId(layerDragStart.selectedLayerId);
+      setSelectedLayerIds(layerDragStart.selectedLayerIds);
+      setGenerateDialog((currentDialog) =>
+        updateGenerateDialogForLayerPointerDown(currentDialog, layer.id),
+      );
+      dragStateRef.current = layerDragStart.dragState;
+    },
+    [
+      canvasViewportRef,
+      canvasGenerationDialogs,
+      effectiveTool,
+      generateDialog?.mode,
+      isPickingCharacterSpecFromCanvas,
+      isPickingGenerationReferenceFromCanvas,
+      isPickingQuickEditReferenceFromCanvas,
+      isPickingCharacterReferenceFromCanvas,
+      isPickingIconSpecFromCanvas,
+      isPickingPublicationReferenceFromCanvas,
+      layers,
+      pickGenerationReferenceFromLayer,
+      pickQuickEditReferenceFromLayer,
+      pickCharacterReferenceFromLayer,
+      pickCharacterSpecFromLayer,
+      pickIconSpecFromLayer,
+      pickPublicationReferenceFromLayer,
+      pickUiDesignSpecFromLayer,
+      selectedLayerIds,
+      setGenerateDialog,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+      startPan,
+      viewport.scale,
+    ],
+  );
+
+  const handleLayerClick = useCallback(
+    (event: ReactMouseEvent<HTMLElement>, layer: CanvasLayer) => {
+      // 测试环境和辅助技术可能只触发 click；
+      // 用 click 兜底选中，真实拖拽仍由 pointerDown 负责。
+      event.stopPropagation();
+      if (suppressNextLayerClickRef.current) {
+        suppressNextLayerClickRef.current = false;
+        return;
+      }
+      if (isPickingCharacterSpecFromCanvas) {
+        return;
+      }
+      if (isPickingGenerationReferenceFromCanvas) {
+        return;
+      }
+      if (isPickingQuickEditReferenceFromCanvas) {
+        return;
+      }
+      if (isPickingCharacterReferenceFromCanvas) {
+        return;
+      }
+      if (isPickingIconSpecFromCanvas) {
+        return;
+      }
+      if (isPickingPublicationReferenceFromCanvas) {
+        return;
+      }
+      if (event.shiftKey || isShiftPressedRef.current) {
+        return;
+      }
+      setSelectedLayerId(layer.id);
+      setSelectedLayerIds([layer.id]);
+      setGenerateDialog((currentDialog) =>
+        updateGenerateDialogForLayerClick(currentDialog),
+      );
+      onCloseImageContextMenu();
+    },
+    [
+      isPickingCharacterSpecFromCanvas,
+      isPickingGenerationReferenceFromCanvas,
+      isPickingQuickEditReferenceFromCanvas,
+      isPickingCharacterReferenceFromCanvas,
+      isPickingIconSpecFromCanvas,
+      isPickingPublicationReferenceFromCanvas,
+      onCloseImageContextMenu,
+      setGenerateDialog,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+    ],
+  );
+
+  const handleGenerationFramePointerDown = useCallback(
+    (
+      event: ReactPointerEvent<HTMLDivElement>,
+      dialog: CanvasGenerationDialogState,
+    ) => {
+      if (!dialog.placeholder) {
+        return;
+      }
+      const button = getPointerButton(event);
+      if (button === 1 || effectiveTool === 'hand') {
+        event.stopPropagation();
+        startPan(event);
+        return;
+      }
+      if (button !== 0) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      const pointer = getPointerClient(event);
+      canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
+      const isMultiSelectGesture = event.shiftKey || isShiftPressedRef.current;
+      if (!isMultiSelectGesture) {
+        activateCanvasGenerationDialog(dialog);
+      }
+      const frameDragStart = createGenerationFrameSelectionStart({
+        dialog,
+        layers,
+        generationDialogs: canvasGenerationDialogs,
+        selectedLayerIds,
+        isMultiSelectGesture,
+        pointerId: getPointerId(event),
+        pointer,
+        viewportScale: viewport.scale,
+      });
+      setSelectedLayerId(frameDragStart.selectedLayerId);
+      setSelectedLayerIds(frameDragStart.selectedLayerIds);
+      dragStateRef.current = frameDragStart.dragState;
+    },
+    [
+      activateCanvasGenerationDialog,
+      canvasViewportRef,
+      canvasGenerationDialogs,
+      effectiveTool,
+      layers,
+      selectedLayerIds,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+      startPan,
+      viewport.scale,
+    ],
+  );
+
+  const handleMinimapPointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLButtonElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+      const pointer = getPointerClient(event);
+      canvasViewportRef.current?.setPointerCapture?.(event.pointerId);
+      dragStateRef.current = createMinimapDragState({
+        pointerId: getPointerId(event),
+        pointer,
+        viewport,
+        minimapScale,
+      });
+    },
+    [canvasViewportRef, minimapScale, viewport],
+  );
+
+  const handlePointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (canvasMarquee && canvasMarquee.pointerId === event.pointerId) {
+        event.preventDefault();
+        const rect = canvasViewportRef.current?.getBoundingClientRect();
+        const currentPoint = getCanvasPointFromPointer({
+          pointer: getPointerClient(event),
+          rect,
+        });
+        setCanvasMarquee((currentMarquee) =>
+          currentMarquee
+            ? {
+                ...currentMarquee,
+                currentX: currentPoint.x,
+                currentY: currentPoint.y,
+              }
+            : null,
+        );
+        const selectedIds = selectCanvasObjectsInsideMarquee({
+          marquee: canvasMarquee,
+          currentPoint,
+          layers,
+          generationDialogs: canvasGenerationDialogs,
+          viewport,
+        });
+        setSelectedLayerIds(selectedIds);
+        setSelectedLayerId(
+          selectedIds.find(
+            (selectedId) => !selectedId.startsWith('generation-dialog:'),
+          ) ?? null,
+        );
+        return;
+      }
+
+      const dragState = dragStateRef.current;
+      const pointerId = getPointerId(event);
+      if (
+        !dragState ||
+        (dragState.pointerId >= 0 &&
+          pointerId >= 0 &&
+          dragState.pointerId !== pointerId)
+      ) {
+        return;
+      }
+
+      if (dragState.kind === 'pan') {
+        const pointer = getPointerClient(event);
+        setViewport(moveViewportFromPan(dragState, pointer));
+        return;
+      }
+
+      if (dragState.kind === 'generation-frame') {
+        const pointer = getPointerClient(event);
+        const movedFrameResult = moveGenerationFramesFromDrag({
+          dragState,
+          generationDialogs: canvasGenerationDialogs,
+          layers,
+          pointer,
+        });
+        setSnapGuide(movedFrameResult.snapGuide);
+        movedFrameResult.generationDialogs.forEach((nextDialog) => {
+          if (!dragState.dialogIds.includes(nextDialog.id)) {
+            return;
+          }
+          updateCanvasGenerationDialogById(nextDialog.id, () => nextDialog);
+        });
+        setLayers((currentLayers) =>
+          moveDragSelectedLayers({
+            dragState,
+            layers: currentLayers,
+            snapOffset: movedFrameResult.snapOffset,
+            pointer,
+          }),
+        );
+        return;
+      }
+
+      if (dragState.kind === 'minimap') {
+        const pointer = getPointerClient(event);
+        const nextDragState = updateMinimapDragMovement(dragState, pointer);
+        if (nextDragState !== dragState) {
+          dragStateRef.current = nextDragState;
+        }
+        if (nextDragState.moved) {
+          updateViewportFromMinimapDrag(nextDragState, pointer.x, pointer.y);
+        }
+        return;
+      }
+
+      const pointer = getPointerClient(event);
+      const movedLayers = moveLayersFromDrag({
+        dragState,
+        layers,
+        generationDialogs: canvasGenerationDialogs,
+        pointer,
+      });
+      if (!movedLayers) {
+        return;
+      }
+      setSnapGuide(movedLayers.snapGuide);
+      setLayers(movedLayers.layers);
+      const movedFrameResult = moveGenerationFramesFromDrag({
+        dragState,
+        generationDialogs: canvasGenerationDialogs,
+        layers,
+        snapOffset: movedLayers.snapOffset,
+        pointer,
+      });
+      movedFrameResult.generationDialogs.forEach((nextDialog) => {
+        if (!dragState.generationDialogIds?.includes(nextDialog.id)) {
+          return;
+        }
+        updateCanvasGenerationDialogById(nextDialog.id, () => nextDialog);
+      });
+    },
+    [
+      canvasMarquee,
+      canvasViewportRef,
+      canvasGenerationDialogs,
+      layers,
+      setLayers,
+      setSelectedLayerId,
+      setSelectedLayerIds,
+      setViewport,
+      updateCanvasGenerationDialogById,
+      updateViewportFromMinimapDrag,
+      viewport,
+    ],
+  );
+
+  const finishDrag = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      if (canvasMarquee && canvasMarquee.pointerId === event.pointerId) {
+        event.preventDefault();
+        setCanvasMarquee(null);
+        if (canvasViewportRef.current?.hasPointerCapture?.(event.pointerId)) {
+          canvasViewportRef.current.releasePointerCapture?.(event.pointerId);
+        }
+        return;
+      }
+
+      const dragState = dragStateRef.current;
+      const pointerId = getPointerId(event);
+      if (
+        dragState &&
+        (dragState.pointerId < 0 ||
+          pointerId < 0 ||
+          dragState.pointerId === pointerId)
+      ) {
+        if (dragState.kind === 'minimap' && !dragState.moved) {
+          const pointer = getPointerClient(event);
+          moveViewportFromMinimapPointer(pointer.x, pointer.y);
+        }
+        dragStateRef.current = null;
+        setIsPanning(false);
+        setSnapGuide(null);
+        if (canvasViewportRef.current?.hasPointerCapture?.(event.pointerId)) {
+          canvasViewportRef.current.releasePointerCapture?.(event.pointerId);
+        }
+      }
+    },
+    [canvasMarquee, canvasViewportRef, moveViewportFromMinimapPointer],
+  );
+
+  return useMemo(
+    () => ({
+      canvasMarquee,
+      isPanning,
+      snapGuide,
+      effectiveTool,
+      setIsSpacePanning,
+      setShiftPressed,
+      clearActiveInteraction,
+      handleCanvasPointerDown,
+      handleLayerPointerDown,
+      handleLayerClick,
+      handleGenerationFramePointerDown,
+      handleMinimapPointerDown,
+      handlePointerMove,
+      finishDrag,
+    }),
+    [
+      canvasMarquee,
+      clearActiveInteraction,
+      effectiveTool,
+      finishDrag,
+      handleCanvasPointerDown,
+      handleGenerationFramePointerDown,
+      handleLayerClick,
+      handleLayerPointerDown,
+      handleMinimapPointerDown,
+      handlePointerMove,
+      isPanning,
+      setShiftPressed,
+      snapGuide,
+    ],
+  );
+}
diff --git a/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx b/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx
new file mode 100644
index 000000000..f92087cd2
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx
@@ -0,0 +1,736 @@
+/* @vitest-environment jsdom */
+
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import type {
+  CanvasLayer,
+  CanvasTool,
+  EditorAsset,
+  EditorAssetFolder,
+  GenerateDialogState,
+  QuickEditPanelState,
+  SidebarPanel,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasUploadWorkflow } from './useImageCanvasUploadWorkflow';
+
+const createEditorAssetMock = vi.hoisted(() => vi.fn());
+const createEditorProjectResourceMock = vi.hoisted(() => vi.fn());
+const uploadEditorSeedanceReferenceFileMock = vi.hoisted(() => vi.fn());
+const uploadEditorMediaAssetFileMock = vi.hoisted(() => vi.fn());
+let createdMediaElements: HTMLMediaElement[] = [];
+
+vi.mock('../../services/image-editor/editorProjectClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/image-editor/editorProjectClient')
+  >('../../services/image-editor/editorProjectClient');
+  return {
+    ...actual,
+    createEditorAsset: createEditorAssetMock,
+    createEditorProjectResource: createEditorProjectResourceMock,
+  };
+});
+
+vi.mock('../../services/image-editor/editorReferenceUploadClient', () => ({
+  uploadEditorSeedanceReferenceFile: uploadEditorSeedanceReferenceFileMock,
+}));
+
+vi.mock('../../services/image-editor/editorMediaAssetUploadClient', () => ({
+  uploadEditorMediaAssetFile: uploadEditorMediaAssetFileMock,
+}));
+
+function createDefaultFolder(): EditorAssetFolder {
+  return {
+    id: 'project',
+    label: '项目素材',
+    collapsed: false,
+    systemDefault: true,
+    persisted: true,
+  };
+}
+
+function createTestFile(name = '上传素材.png') {
+  return new File(['image'], name, { type: 'image/png' });
+}
+
+function createSizedPngFile(name: string, width: number, height: number) {
+  const bytes = new Uint8Array([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    0,
+    0,
+    0,
+    13,
+    0x49,
+    0x48,
+    0x44,
+    0x52,
+    (width >> 24) & 0xff,
+    (width >> 16) & 0xff,
+    (width >> 8) & 0xff,
+    width & 0xff,
+    (height >> 24) & 0xff,
+    (height >> 16) & 0xff,
+    (height >> 8) & 0xff,
+    height & 0xff,
+    8,
+    6,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+  ]);
+  return new File([bytes], name, { type: 'image/png' });
+}
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+
+function UploadWorkflowHarness({
+  canAccessProtectedData = true,
+  openEditorLoginModal = vi.fn(),
+  activeTool = 'select',
+  projectId = 'project-1',
+}: {
+  canAccessProtectedData?: boolean;
+  openEditorLoginModal?: (postLoginAction?: (() => void) | null) => void;
+  activeTool?: CanvasTool;
+  projectId?: string | null;
+}) {
+  const [assetFolders, setAssetFolders] = useState<EditorAssetFolder[]>([
+    createDefaultFolder(),
+  ]);
+  const [assets, setAssets] = useState<EditorAsset[]>([]);
+  const [layers, setLayers] = useState<CanvasLayer[]>([]);
+  const [generateDialog, setGenerateDialog] =
+    useState<GenerateDialogState | null>(null);
+  const [, setQuickEditPanel] = useState<QuickEditPanelState | null>(null);
+  const [activeSidebarPanel] = useState<SidebarPanel | null>('assets');
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>(null);
+  const uploadIndexRef = useRef(0);
+
+  const workflow = useImageCanvasUploadWorkflow({
+    canAccessProtectedData,
+    openEditorLoginModal,
+    projectId,
+    assetFolders,
+    activeUploadFolderId: 'project',
+    canvasSize: { width: 900, height: 640 },
+    viewport: { x: 10, y: 20, scale: 2 },
+    activeTool,
+    allocateUploadIndex: () => {
+      uploadIndexRef.current += 1;
+      return uploadIndexRef.current;
+    },
+    setAssetFolders,
+    setAssets,
+    setLayers,
+    setGenerateDialog,
+    setQuickEditPanel,
+    appendCanvasLayersWithResources: (nextLayers) => {
+      setLayers((currentLayers) => [...currentLayers, ...nextLayers]);
+    },
+    selectSingleLayer: setSelectedLayerId,
+  });
+
+  return (
+    <div>
+      <input
+        ref={workflow.uploadInputRef}
+        type="file"
+        aria-label="上传图片文件"
+        multiple
+        onChange={workflow.handleUploadInputChange}
+      />
+      <span data-testid="assets">
+        {assets
+          .map(
+            (asset) =>
+              `${asset.id}:${asset.label}:${asset.folderId}:${asset.uploadStatus ?? 'ready'}:${asset.uploadMessage ?? '-'}:${asset.width}x${asset.height}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="folders">
+        {assetFolders
+          .map(
+            (folder) =>
+              `${folder.id}:${folder.collapsed ? 'collapsed' : 'open'}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="layers">
+        {layers
+          .map(
+            (layer) =>
+              `${layer.id}:${layer.title}:${layer.sourceAssetId}:${layer.x}:${layer.y}:${layer.width}x${layer.height}`,
+          )
+          .join('|')}
+      </span>
+      <span data-testid="sidebar">{activeSidebarPanel ?? '-'}</span>
+      <span data-testid="selected-layer">{selectedLayerId ?? '-'}</span>
+      <span data-testid="dialog">
+        {generateDialog
+          ? `${generateDialog.mode}:${generateDialog.status}:${generateDialog.characterSpecReference?.label ?? '-'}:${generateDialog.characterReferences?.length ?? 0}:${generateDialog.iconSpecReference?.label ?? '-'}:${generateDialog.specReference?.label ?? '-'}:${generateDialog.generationReferences?.length ?? 0}:${generateDialog.generationReferences?.[0]?.label ?? '-'}:${generateDialog.generationReferences?.map((reference) => `${reference.mediaType ?? 'image'}:${reference.src}:${reference.objectKey ?? '-'}:${reference.resourceId ?? '-'}:${reference.sourceAssetId ?? '-'}`).join(',') || '-'}`
+          : '-'}
+      </span>
+      <button
+        type="button"
+        onClick={() => workflow.addUploadedFiles([createTestFile()])}
+      >
+        上传素材
+      </button>
+      <button type="button" onClick={() => workflow.requestUpload('asset')}>
+        请求素材上传
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.addUploadedFiles([createTestFile('画布素材.png')], {
+            addToCanvas: true,
+            canvasPoint: { x: 110, y: 120 },
+          })
+        }
+      >
+        上传到画布
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflow.addUploadedFiles(
+            [createSizedPngFile('原始尺寸素材.png', 1536, 1024)],
+            {
+              addToCanvas: true,
+              canvasPoint: { x: 110, y: 120 },
+            },
+          )
+        }
+      >
+        上传原始尺寸到画布
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setGenerateDialog({
+            mode: 'generate',
+            prompt: '',
+            status: 'failed',
+            errorMessage: '旧错误',
+          })
+        }
+      >
+        准备图片生成
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setGenerateDialog({
+            mode: 'character',
+            prompt: '',
+            status: 'failed',
+            errorMessage: '旧错误',
+          })
+        }
+      >
+        准备角色生成
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setGenerateDialog({
+            mode: 'spec',
+            specType: 'ui',
+            prompt: '',
+            status: 'failed',
+            errorMessage: '旧错误',
+          })
+        }
+      >
+        准备规范生成
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          setGenerateDialog({
+            mode: 'video',
+            prompt: '',
+            status: 'failed',
+            generationReferences: [],
+          })
+        }
+      >
+        准备视频生成
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.setUploadTarget('generation-reference')}
+      >
+        选择生成参考图
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.setUploadTarget('spec-reference')}
+      >
+        选择规范参考图
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.setUploadTarget('character-spec')}
+      >
+        选择角色规范
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.requestUpload('character-spec')}
+      >
+        请求角色规范上传
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.setUploadTarget('video-reference-video')}
+      >
+        选择参考视频
+      </button>
+      <button
+        type="button"
+        onClick={() => workflow.setUploadTarget('video-reference-audio')}
+      >
+        选择参考音频
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasUploadWorkflow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createEditorAssetMock.mockImplementation(async (input) => ({
+      assetId: `persisted-${input.label}`,
+      folderId: input.folderId,
+      label: input.label,
+      imageSrc: input.imageSrc,
+      width: input.width,
+      height: input.height,
+      sourceType: input.sourceType,
+      objectKey: 'object-key-uploaded',
+      assetObjectId: 'asset-object-uploaded',
+    }));
+    createEditorProjectResourceMock.mockImplementation(
+      async (projectId, input) => ({
+        resourceId: `resource-${input.objectKey ?? input.imageSrc.slice(0, 8)}`,
+        projectId,
+        imageSrc: input.imageSrc,
+        width: input.width,
+        height: input.height,
+        sourceType: input.sourceType,
+        objectKey: input.objectKey,
+        assetObjectId: input.assetObjectId,
+        durationSeconds: input.durationSeconds,
+      }),
+    );
+    uploadEditorSeedanceReferenceFileMock.mockImplementation(
+      async (file: File, mediaType: 'video' | 'audio') => ({
+        src: `https://signed.example.com/${mediaType}/${file.name}`,
+        objectKey: `generated-character-drafts/editor/seedance-references/${mediaType}/${file.name}`,
+        assetObjectId: `assetobj-${mediaType}`,
+      }),
+    );
+    uploadEditorMediaAssetFileMock.mockImplementation(
+      async (file: File, mediaType: 'video' | 'audio') => ({
+        src: `https://signed.example.com/editor/${mediaType}/${file.name}`,
+        legacyPublicPath: `/generated-character-drafts/editor/asset-library/${mediaType}/${file.name}`,
+        objectKey: `generated-character-drafts/editor/asset-library/${mediaType}/${file.name}`,
+        assetObjectId: `assetobj-editor-${mediaType}`,
+      }),
+    );
+    Object.defineProperty(HTMLMediaElement.prototype, 'duration', {
+      configurable: true,
+      value: 4,
+    });
+    createdMediaElements = [];
+    const originalCreateElement = document.createElement.bind(document);
+    vi.spyOn(document, 'createElement').mockImplementation((tagName, options) => {
+      const element = originalCreateElement(tagName, options);
+      if (tagName === 'video' || tagName === 'audio') {
+        createdMediaElements.push(element as HTMLMediaElement);
+      }
+      return element;
+    });
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: vi.fn(() => 'blob:media'),
+    });
+    Object.defineProperty(URL, 'revokeObjectURL', {
+      configurable: true,
+      value: vi.fn(),
+    });
+    vi.spyOn(HTMLMediaElement.prototype, 'load').mockImplementation(() => undefined);
+  });
+
+  it('opens login before creating placeholders and resumes the same upload after login', async () => {
+    const openEditorLoginModal = vi.fn();
+    const { rerender } = render(
+      <UploadWorkflowHarness
+        canAccessProtectedData={false}
+        openEditorLoginModal={openEditorLoginModal}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '上传素材' }));
+
+    expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('assets').textContent).toBe('');
+
+    const resumeUpload = openEditorLoginModal.mock.calls[0]?.[0];
+    rerender(
+      <UploadWorkflowHarness
+        canAccessProtectedData
+        openEditorLoginModal={openEditorLoginModal}
+      />,
+    );
+    act(() => {
+      (resumeUpload as () => void)();
+    });
+
+    await waitFor(() => {
+      expect(createEditorAssetMock).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId('assets').textContent).toContain(
+        'persisted-上传素材.png:上传素材.png:project:ready:-',
+      );
+    });
+  });
+
+  it('opens login instead of the asset file picker when protected data is unavailable', () => {
+    const openEditorLoginModal = vi.fn();
+    render(
+      <UploadWorkflowHarness
+        canAccessProtectedData={false}
+        openEditorLoginModal={openEditorLoginModal}
+      />,
+    );
+    const uploadInput = screen.getByLabelText(
+      '上传图片文件',
+    ) as HTMLInputElement;
+    const clickUploadInput = vi.spyOn(uploadInput, 'click');
+
+    fireEvent.click(screen.getByRole('button', { name: '请求素材上传' }));
+
+    expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+    expect(clickUploadInput).not.toHaveBeenCalled();
+  });
+
+  it('opens login instead of the reference file picker when protected data is unavailable', () => {
+    const openEditorLoginModal = vi.fn();
+    render(
+      <UploadWorkflowHarness
+        canAccessProtectedData={false}
+        openEditorLoginModal={openEditorLoginModal}
+      />,
+    );
+    const uploadInput = screen.getByLabelText(
+      '上传图片文件',
+    ) as HTMLInputElement;
+    const clickUploadInput = vi.spyOn(uploadInput, 'click');
+
+    fireEvent.click(screen.getByRole('button', { name: '请求角色规范上传' }));
+
+    expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+    expect(clickUploadInput).not.toHaveBeenCalled();
+  });
+
+  it('creates an uploading asset card, adds a canvas layer, keeps the sidebar, and patches the layer with the persisted asset id', async () => {
+    const deferredAsset = createDeferred<{
+      assetId: string;
+      folderId: string;
+      label: string;
+      imageSrc: string;
+      width: number;
+      height: number;
+      sourceType: 'uploaded';
+      objectKey: string;
+      assetObjectId: string;
+    }>();
+    createEditorAssetMock.mockReturnValueOnce(deferredAsset.promise);
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '上传到画布' }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('assets').textContent).toContain(
+        'upload-1:画布素材.png:project:uploading:上传中',
+      );
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-upload-1:画布素材.png:upload-1:-160:-107.5',
+      );
+    });
+    expect(screen.getByTestId('sidebar').textContent).toBe('assets');
+    expect(screen.getByTestId('selected-layer').textContent).toBe(
+      'layer-upload-1',
+    );
+
+    deferredAsset.resolve({
+      assetId: 'asset-persisted-canvas',
+      folderId: 'project',
+      label: '画布素材.png',
+      imageSrc: 'data:image/png;base64,Y2FudmFz',
+      width: 420,
+      height: 315,
+      sourceType: 'uploaded',
+      objectKey: 'object-key-canvas',
+      assetObjectId: 'asset-object-canvas',
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('assets').textContent).toContain(
+        'asset-persisted-canvas:画布素材.png:project:ready:-',
+      );
+      expect(screen.getByTestId('layers').textContent).toContain(
+        'layer-upload-1:画布素材.png:asset-persisted-canvas:-160:-107.5',
+      );
+    });
+  });
+
+  it('uses the uploaded image resolution before creating the canvas layer and persisted asset', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(
+      screen.getByRole('button', { name: '上传原始尺寸到画布' }),
+    );
+
+    await waitFor(() => {
+      expect(createEditorAssetMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          label: '原始尺寸素材.png',
+          width: 1536,
+          height: 1024,
+        }),
+      );
+    });
+    expect(screen.getByTestId('assets').textContent).toContain(
+      'persisted-原始尺寸素材.png:原始尺寸素材.png:project:ready:-:1536x1024',
+    );
+    expect(screen.getByTestId('layers').textContent).toContain(
+      'layer-upload-1:原始尺寸素材.png:persisted-原始尺寸素材.png:-718:-462:1536x1024',
+    );
+  });
+
+  it('marks upload cards as failed and reopens login on auth errors returned by asset creation', async () => {
+    const openEditorLoginModal = vi.fn();
+    createEditorAssetMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+    render(
+      <UploadWorkflowHarness openEditorLoginModal={openEditorLoginModal} />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '上传素材' }));
+
+    await waitFor(() => {
+      expect(openEditorLoginModal).toHaveBeenCalledTimes(1);
+      expect(screen.getByTestId('assets').textContent).toContain(
+        'upload-1:上传素材.png:project:failed:请先登录',
+      );
+    });
+  });
+
+  it('dispatches file input uploads to generation references and resets failed state', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '准备角色生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择角色规范' }));
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toBe(
+        'character:failed:-:0:-:-:0:-:-',
+      );
+    });
+
+    fireEvent.change(screen.getByLabelText('上传图片文件'), {
+      target: {
+        files: [createTestFile('角色规范.png')],
+      },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        'character:idle:角色规范.png:0:-:-',
+      );
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: 'data:image/png;base64,aW1hZ2U=',
+        width: 420,
+        height: 315,
+        sourceType: 'uploaded',
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+  });
+
+  it('dispatches file input uploads to normal generation references', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '准备图片生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择生成参考图' }));
+    fireEvent.change(screen.getByLabelText('上传图片文件'), {
+      target: {
+        files: [createTestFile('普通参考.png')],
+      },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        'generate:idle:-:0:-:-:1:普通参考.png',
+      );
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: 'data:image/png;base64,aW1hZ2U=',
+        width: 420,
+        height: 315,
+        sourceType: 'uploaded',
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+  });
+
+  it('dispatches file input uploads to spec reference images', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '准备规范生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择规范参考图' }));
+    fireEvent.change(screen.getByLabelText('上传图片文件'), {
+      target: {
+        files: [createTestFile('UI参考.png')],
+      },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        'spec:idle:-:0:-:UI参考.png',
+      );
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: 'data:image/png;base64,aW1hZ2U=',
+        width: 420,
+        height: 315,
+        sourceType: 'uploaded',
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+  });
+
+  it('uploads Seedance reference videos through OSS and stores object keys instead of data URLs', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '准备视频生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择参考视频' }));
+    const uploadInput = screen.getByLabelText('上传图片文件');
+    fireEvent.change(uploadInput, {
+      target: {
+        files: [new File(['video'], '动作参考.mp4', { type: 'video/mp4' })],
+      },
+    });
+    act(() => {
+      createdMediaElements[0]?.onloadedmetadata?.(new Event('loadedmetadata'));
+    });
+
+    await waitFor(() => {
+      expect(uploadEditorSeedanceReferenceFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ name: '动作参考.mp4' }),
+        'video',
+      );
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        'video:idle:-:0:-:-:1:动作参考.mp4:video:https://signed.example.com/video/动作参考.mp4:generated-character-drafts/editor/seedance-references/video/动作参考.mp4',
+      );
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: 'https://signed.example.com/video/动作参考.mp4',
+        objectKey:
+          'generated-character-drafts/editor/seedance-references/video/动作参考.mp4',
+        assetObjectId: 'assetobj-video',
+        width: 560,
+        height: 315,
+        sourceType: 'uploaded',
+        durationSeconds: 4,
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('dialog').textContent).not.toContain('data:video');
+  });
+
+  it('uploads Seedance reference audios through OSS and stores object keys instead of data URLs', async () => {
+    render(<UploadWorkflowHarness />);
+
+    fireEvent.click(screen.getByRole('button', { name: '准备视频生成' }));
+    fireEvent.click(screen.getByRole('button', { name: '选择参考音频' }));
+    fireEvent.change(screen.getByLabelText('上传图片文件'), {
+      target: {
+        files: [new File(['audio'], '旁白.mp3', { type: 'audio/mpeg' })],
+      },
+    });
+    act(() => {
+      createdMediaElements[0]?.onloadedmetadata?.(new Event('loadedmetadata'));
+    });
+
+    await waitFor(() => {
+      expect(uploadEditorSeedanceReferenceFileMock).toHaveBeenCalledWith(
+        expect.objectContaining({ name: '旁白.mp3' }),
+        'audio',
+      );
+      expect(screen.getByTestId('dialog').textContent).toContain(
+        'video:idle:-:0:-:-:1:旁白.mp3:audio:https://signed.example.com/audio/旁白.mp3:generated-character-drafts/editor/seedance-references/audio/旁白.mp3',
+      );
+    });
+    expect(createEditorProjectResourceMock).toHaveBeenCalledWith(
+      'project-1',
+      expect.objectContaining({
+        imageSrc: 'https://signed.example.com/audio/旁白.mp3',
+        objectKey:
+          'generated-character-drafts/editor/seedance-references/audio/旁白.mp3',
+        assetObjectId: 'assetobj-audio',
+        width: 420,
+        height: 120,
+        sourceType: 'uploaded',
+        durationSeconds: 4,
+      }),
+    );
+    expect(createEditorAssetMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId('dialog').textContent).not.toContain('data:audio');
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasUploadWorkflow.ts b/src/components/image-editor/useImageCanvasUploadWorkflow.ts
new file mode 100644
index 000000000..98263c947
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasUploadWorkflow.ts
@@ -0,0 +1,1121 @@
+import {
+  type ChangeEvent,
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+
+import { ApiClientError } from '../../services/apiClient';
+import { uploadEditorMediaAssetFile } from '../../services/image-editor/editorMediaAssetUploadClient';
+import {
+  createEditorAsset,
+  createEditorProjectResource,
+} from '../../services/image-editor/editorProjectClient';
+import { uploadEditorSeedanceReferenceFile } from '../../services/image-editor/editorReferenceUploadClient';
+import type {
+  CanvasMediaType,
+  CanvasLayer,
+  CanvasTool,
+  CanvasViewport,
+  CharacterReferenceImage,
+  EditorAsset,
+  EditorAssetFolder,
+  GenerateDialogState,
+  QuickEditPanelState,
+  UploadTarget,
+} from './ImageCanvasEditorTypes';
+import {
+  SEEDANCE_REFERENCE_FILE_LIMITS,
+  isImageFile,
+  resolveEditorAssetUploadMediaType,
+  isSeedanceReferenceAudioFile,
+  isSeedanceReferenceImageFile,
+  isSeedanceReferenceVideoFile,
+  probeImageFileDimensions,
+  probeMediaDurationSeconds,
+  readFileAsDataUrl,
+  readImageFileAsDataUrl,
+} from './ImageCanvasFileModel';
+import {
+  applyGenerationReferenceUpload,
+  applyQuickEditReferenceUpload,
+  applyMeasuredUploadAssetSize,
+  applyPersistedUploadAsset,
+  applyUploadAssetCreateFailure,
+  applyUploadAssetCreatePending,
+  applyUploadAssetReadFailure,
+  applyUploadAssetReadSuccess,
+  bindUploadLayerToPersistedAsset,
+  createUploadCanvasLayer,
+  createUploadedGenerationReference,
+  createUploadingAssetPlaceholder,
+  expandUploadFolder,
+  resizeUploadCanvasLayerToImage,
+  resolveUploadFolderId,
+} from './ImageCanvasUploadModel';
+
+type UploadFilesOptions = {
+  folderId?: string;
+  canvasPoint?: { x: number; y: number };
+  addToCanvas?: boolean;
+};
+
+type UploadRequestOptions = {
+  addToCanvas?: boolean;
+};
+
+type UploadAssetFileOptions = UploadFilesOptions & {
+  uploadIndex: number;
+};
+
+type UseImageCanvasUploadWorkflowOptions = {
+  canAccessProtectedData: boolean;
+  openEditorLoginModal: (postLoginAction?: (() => void) | null) => void;
+  projectId?: string | null;
+  assetFolders: EditorAssetFolder[];
+  activeUploadFolderId: string;
+  canvasSize: { width: number; height: number };
+  viewport: CanvasViewport;
+  activeTool: CanvasTool;
+  allocateUploadIndex: () => number;
+  setAssetFolders: Dispatch<SetStateAction<EditorAssetFolder[]>>;
+  setAssets: Dispatch<SetStateAction<EditorAsset[]>>;
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  setGenerateDialog: Dispatch<SetStateAction<GenerateDialogState | null>>;
+  setQuickEditPanel: Dispatch<SetStateAction<QuickEditPanelState | null>>;
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+};
+
+function isEditorAuthError(error: unknown) {
+  return (
+    error instanceof ApiClientError &&
+    (error.status === 401 || error.status === 403)
+  );
+}
+
+function resolveReferenceFallbackSize(mediaType: CanvasMediaType) {
+  if (mediaType === 'video') {
+    return { width: 560, height: 315 };
+  }
+  if (mediaType === 'audio') {
+    return { width: 420, height: 120 };
+  }
+  return { width: 420, height: 315 };
+}
+
+export function useImageCanvasUploadWorkflow({
+  canAccessProtectedData,
+  openEditorLoginModal,
+  projectId,
+  assetFolders,
+  activeUploadFolderId,
+  canvasSize,
+  viewport,
+  activeTool,
+  allocateUploadIndex,
+  setAssetFolders,
+  setAssets,
+  setLayers,
+  setGenerateDialog,
+  setQuickEditPanel,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+}: UseImageCanvasUploadWorkflowOptions) {
+  const uploadInputRef = useRef<HTMLInputElement | null>(null);
+  const canAccessProtectedDataRef = useRef(canAccessProtectedData);
+  const uploadTargetRef = useRef<UploadTarget>('asset');
+  const uploadRequestOptionsRef = useRef<UploadRequestOptions>({});
+  const [uploadTarget, setUploadTargetState] = useState<UploadTarget>('asset');
+
+  canAccessProtectedDataRef.current = canAccessProtectedData;
+
+  const setUploadTarget: Dispatch<SetStateAction<UploadTarget>> = useCallback(
+    (nextTarget) => {
+      const resolvedTarget =
+        typeof nextTarget === 'function'
+          ? nextTarget(uploadTargetRef.current)
+          : nextTarget;
+      uploadTargetRef.current = resolvedTarget;
+      setUploadTargetState(resolvedTarget);
+    },
+    [],
+  );
+
+  const createPersistedReference = useCallback(
+    async ({
+      idPrefix,
+      index,
+      file,
+      fallbackLabel,
+      imageSrc,
+      mediaType = 'image',
+      mimeType,
+      sizeBytes,
+      durationSeconds,
+      objectKey,
+      assetObjectId,
+    }: {
+      idPrefix: string;
+      index?: number;
+      file: File;
+      fallbackLabel: string;
+      imageSrc: string;
+      mediaType?: CanvasMediaType;
+      mimeType?: string;
+      sizeBytes?: number;
+      durationSeconds?: number;
+      objectKey?: string | null;
+      assetObjectId?: string | null;
+    }): Promise<CharacterReferenceImage> => {
+      const fallbackSize = resolveReferenceFallbackSize(mediaType);
+      const imageDimensions =
+        mediaType === 'image'
+          ? await probeImageFileDimensions(file).catch(() => null)
+          : null;
+      const width = imageDimensions?.width ?? fallbackSize.width;
+      const height = imageDimensions?.height ?? fallbackSize.height;
+      if (projectId) {
+        const resource = await createEditorProjectResource(projectId, {
+          imageSrc,
+          ...(objectKey ? { objectKey } : {}),
+          ...(assetObjectId ? { assetObjectId } : {}),
+          width,
+          height,
+          sourceType: 'uploaded',
+          ...(durationSeconds ? { durationSeconds } : {}),
+        });
+        return createUploadedGenerationReference({
+          idPrefix,
+          index,
+          fileName: file.name,
+          fallbackLabel,
+          imageSrc,
+          mediaType,
+          mimeType,
+          sizeBytes,
+          durationSeconds,
+          objectKey,
+          assetObjectId,
+          resourceId: resource.resourceId,
+        });
+      }
+
+      const uploadFolderId = resolveUploadFolderId({
+        assetFolders,
+        activeUploadFolderId,
+      });
+      const asset = await createEditorAsset({
+        folderId: uploadFolderId,
+        label: file.name || fallbackLabel,
+        imageSrc,
+        ...(objectKey ? { objectKey } : {}),
+        ...(assetObjectId ? { assetObjectId } : {}),
+        width,
+        height,
+        sourceType: 'uploaded',
+        ...(durationSeconds ? { durationSeconds } : {}),
+      });
+      return createUploadedGenerationReference({
+        idPrefix,
+        index,
+        fileName: file.name,
+        fallbackLabel,
+        imageSrc,
+        mediaType,
+        mimeType,
+        sizeBytes,
+        durationSeconds,
+        objectKey,
+        assetObjectId,
+        sourceAssetId: asset.assetId,
+      });
+    },
+    [activeUploadFolderId, assetFolders, projectId],
+  );
+
+  const persistReferenceUploads = useCallback(
+    async (
+      inputs: Array<{
+        idPrefix: string;
+        index?: number;
+        file: File;
+        fallbackLabel: string;
+        imageSrc: string;
+        mediaType?: CanvasMediaType;
+        mimeType?: string;
+        sizeBytes?: number;
+        durationSeconds?: number;
+        objectKey?: string | null;
+        assetObjectId?: string | null;
+      }>,
+    ) => {
+      try {
+        return await Promise.all(inputs.map(createPersistedReference));
+      } catch (error) {
+        if (isEditorAuthError(error)) {
+          openEditorLoginModal();
+          window.alert('请先登录后再上传参考图');
+        } else {
+          window.alert('参考图保存失败，请稍后重试');
+        }
+        return null;
+      }
+    },
+    [createPersistedReference, openEditorLoginModal],
+  );
+
+  const addCharacterSpecReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFile = Array.from(files).find(isImageFile);
+      if (!imageFile) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const imageSrc = await readImageFileAsDataUrl(imageFile);
+      const references = await persistReferenceUploads([
+        {
+          idPrefix: 'upload-character-spec',
+          file: imageFile,
+          fallbackLabel: '角色规范',
+          imageSrc,
+        },
+      ]);
+      if (!references) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'character-spec',
+          references,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addSpecReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFile = Array.from(files).find(isImageFile);
+      if (!imageFile) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const imageSrc = await readImageFileAsDataUrl(imageFile);
+      const references = await persistReferenceUploads([
+        {
+          idPrefix: 'upload-spec-reference',
+          file: imageFile,
+          fallbackLabel: '参考图',
+          imageSrc,
+        },
+      ]);
+      if (!references) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'spec-reference',
+          references,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addCharacterReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFiles = Array.from(files).filter(isImageFile);
+      if (!imageFiles.length) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const references = await Promise.all(
+        imageFiles.map(async (file, index) => ({
+          file,
+          index,
+          imageSrc: await readImageFileAsDataUrl(file),
+        })),
+      );
+      const persistedReferences = await persistReferenceUploads(
+        references.map(({ file, imageSrc, index }) => ({
+          idPrefix: 'upload-character-reference',
+          index,
+          file,
+          fallbackLabel: `参考图${index + 1}`,
+          imageSrc,
+        })),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'character-reference',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addGenerationReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFiles = Array.from(files).filter(isImageFile);
+      if (!imageFiles.length) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const references = await Promise.all(
+        imageFiles.map(async (file, index) => ({
+          file,
+          index,
+          imageSrc: await readImageFileAsDataUrl(file),
+        })),
+      );
+      const persistedReferences = await persistReferenceUploads(
+        references.map(({ file, imageSrc, index }) => ({
+          idPrefix: 'upload-generation-reference',
+          index,
+          file,
+          fallbackLabel: `参考图${index + 1}`,
+          imageSrc,
+        })),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'generation-reference',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addQuickEditReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFiles = Array.from(files).filter(isImageFile);
+      if (!imageFiles.length) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const references = await Promise.all(
+        imageFiles.map(async (file, index) => ({
+          file,
+          index,
+          imageSrc: await readImageFileAsDataUrl(file),
+        })),
+      );
+      const persistedReferences = await persistReferenceUploads(
+        references.map(({ file, imageSrc, index }) => ({
+          idPrefix: 'upload-quick-edit-reference',
+          index,
+          file,
+          fallbackLabel: `参考图${index + 1}`,
+          imageSrc,
+        })),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setQuickEditPanel((currentPanel) =>
+        applyQuickEditReferenceUpload({
+          panel: currentPanel,
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setQuickEditPanel],
+  );
+
+  const addPublicationReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFiles = Array.from(files).filter(isImageFile);
+      if (!imageFiles.length) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const references = await Promise.all(
+        imageFiles.map(async (file, index) => ({
+          file,
+          index,
+          imageSrc: await readImageFileAsDataUrl(file),
+        })),
+      );
+      const persistedReferences = await persistReferenceUploads(
+        references.map(({ file, imageSrc, index }) => ({
+          idPrefix: 'upload-publication-reference',
+          index,
+          file,
+          fallbackLabel: `宣发参考图${index + 1}`,
+          imageSrc,
+        })),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'publication-reference',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addVideoReferenceImageFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFiles = Array.from(files).filter(isSeedanceReferenceImageFile);
+      if (!imageFiles.length) {
+        window.alert('请选择 Seedance 支持的图片文件');
+        return;
+      }
+      if (
+        imageFiles.some(
+          (file) => file.size >= SEEDANCE_REFERENCE_FILE_LIMITS.imageBytes,
+        )
+      ) {
+        window.alert('参考图片单张必须小于 30MB');
+        return;
+      }
+      const references = await Promise.all(
+        imageFiles.map(async (file, index) => ({
+          file,
+          index,
+          src: await readFileAsDataUrl(file),
+        })),
+      );
+      const persistedReferences = await persistReferenceUploads(
+        references.map(({ file, src, index }) => ({
+          idPrefix: 'upload-video-reference-image',
+          index,
+          file,
+          fallbackLabel: `参考图${index + 1}`,
+          imageSrc: src,
+          mediaType: 'image',
+          mimeType: file.type || undefined,
+          sizeBytes: file.size,
+        })),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'video-reference-image',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addVideoReferenceVideoFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const videoFiles = Array.from(files).filter(isSeedanceReferenceVideoFile);
+      if (!videoFiles.length) {
+        window.alert('请选择 mp4 或 mov 视频文件');
+        return;
+      }
+      if (
+        videoFiles.some(
+          (file) => file.size > SEEDANCE_REFERENCE_FILE_LIMITS.videoBytes,
+        )
+      ) {
+        window.alert('参考视频单个不能超过 50MB');
+        return;
+      }
+      const references = await Promise.all(
+        videoFiles.map(async (file, index) => {
+          const durationSeconds = await probeMediaDurationSeconds(file, 'video');
+          return {
+            file,
+            index,
+            durationSeconds,
+          };
+        }),
+      );
+      if (
+        references.some(
+          ({ durationSeconds }) =>
+            Number.isFinite(durationSeconds) &&
+            (durationSeconds < SEEDANCE_REFERENCE_FILE_LIMITS.mediaMinDurationSeconds ||
+              durationSeconds >
+                SEEDANCE_REFERENCE_FILE_LIMITS.mediaMaxDurationSeconds),
+        )
+      ) {
+        window.alert('参考视频时长必须为 2-15 秒');
+        return;
+      }
+      const totalDuration = references.reduce(
+        (sum, reference) =>
+          Number.isFinite(reference.durationSeconds)
+            ? sum + reference.durationSeconds
+            : sum,
+        0,
+      );
+      if (
+        totalDuration >
+        SEEDANCE_REFERENCE_FILE_LIMITS.mediaTotalDurationSeconds
+      ) {
+        window.alert('参考视频总时长不能超过 15 秒');
+        return;
+      }
+      let uploadedReferences: Array<{
+        file: File;
+        index: number;
+        durationSeconds: number;
+        src: string;
+        objectKey: string;
+        assetObjectId: string;
+      }>;
+      try {
+        uploadedReferences = await Promise.all(
+          references.map(async ({ file, index, durationSeconds }) => {
+            const uploaded = await uploadEditorSeedanceReferenceFile(file, 'video');
+            return {
+              file,
+              index,
+              durationSeconds,
+              src: uploaded.src,
+              objectKey: uploaded.objectKey,
+              assetObjectId: uploaded.assetObjectId,
+            };
+          }),
+        );
+      } catch {
+        window.alert('参考视频上传失败，请稍后重试');
+        return;
+      }
+      const persistedReferences = await persistReferenceUploads(
+        uploadedReferences.map(
+          ({ file, src, index, durationSeconds, objectKey, assetObjectId }) => ({
+            idPrefix: 'upload-video-reference-video',
+            index,
+            file,
+            fallbackLabel: `参考视频${index + 1}`,
+            imageSrc: src,
+            mediaType: 'video',
+            mimeType: file.type || undefined,
+            sizeBytes: file.size,
+            durationSeconds,
+            objectKey,
+            assetObjectId,
+          }),
+        ),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'video-reference-video',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addVideoReferenceAudioFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const audioFiles = Array.from(files).filter(isSeedanceReferenceAudioFile);
+      if (!audioFiles.length) {
+        window.alert('请选择 wav 或 mp3 音频文件');
+        return;
+      }
+      if (
+        audioFiles.some(
+          (file) => file.size > SEEDANCE_REFERENCE_FILE_LIMITS.audioBytes,
+        )
+      ) {
+        window.alert('参考音频单个不能超过 15MB');
+        return;
+      }
+      const references = await Promise.all(
+        audioFiles.map(async (file, index) => {
+          const durationSeconds = await probeMediaDurationSeconds(file, 'audio');
+          return {
+            file,
+            index,
+            durationSeconds,
+          };
+        }),
+      );
+      if (
+        references.some(
+          ({ durationSeconds }) =>
+            Number.isFinite(durationSeconds) &&
+            (durationSeconds < SEEDANCE_REFERENCE_FILE_LIMITS.mediaMinDurationSeconds ||
+              durationSeconds >
+                SEEDANCE_REFERENCE_FILE_LIMITS.mediaMaxDurationSeconds),
+        )
+      ) {
+        window.alert('参考音频时长必须为 2-15 秒');
+        return;
+      }
+      const totalDuration = references.reduce(
+        (sum, reference) =>
+          Number.isFinite(reference.durationSeconds)
+            ? sum + reference.durationSeconds
+            : sum,
+        0,
+      );
+      if (
+        totalDuration >
+        SEEDANCE_REFERENCE_FILE_LIMITS.mediaTotalDurationSeconds
+      ) {
+        window.alert('参考音频总时长不能超过 15 秒');
+        return;
+      }
+      let uploadedReferences: Array<{
+        file: File;
+        index: number;
+        durationSeconds: number;
+        src: string;
+        objectKey: string;
+        assetObjectId: string;
+      }>;
+      try {
+        uploadedReferences = await Promise.all(
+          references.map(async ({ file, index, durationSeconds }) => {
+            const uploaded = await uploadEditorSeedanceReferenceFile(file, 'audio');
+            return {
+              file,
+              index,
+              durationSeconds,
+              src: uploaded.src,
+              objectKey: uploaded.objectKey,
+              assetObjectId: uploaded.assetObjectId,
+            };
+          }),
+        );
+      } catch {
+        window.alert('参考音频上传失败，请稍后重试');
+        return;
+      }
+      const persistedReferences = await persistReferenceUploads(
+        uploadedReferences.map(
+          ({ file, src, index, durationSeconds, objectKey, assetObjectId }) => ({
+            idPrefix: 'upload-video-reference-audio',
+            index,
+            file,
+            fallbackLabel: `参考音频${index + 1}`,
+            imageSrc: src,
+            mediaType: 'audio',
+            mimeType: file.type || undefined,
+            sizeBytes: file.size,
+            durationSeconds,
+            objectKey,
+            assetObjectId,
+          }),
+        ),
+      );
+      if (!persistedReferences) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'video-reference-audio',
+          references: persistedReferences,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addIconSpecReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFile = Array.from(files).find(isImageFile);
+      if (!imageFile) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const imageSrc = await readImageFileAsDataUrl(imageFile);
+      const references = await persistReferenceUploads([
+        {
+          idPrefix: 'upload-icon-spec',
+          file: imageFile,
+          fallbackLabel: '图标规范',
+          imageSrc,
+        },
+      ]);
+      if (!references) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'icon-spec',
+          references,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const addUiDesignSpecReferenceFiles = useCallback(
+    async (files: FileList | File[]) => {
+      const imageFile = Array.from(files).find(isImageFile);
+      if (!imageFile) {
+        window.alert('请选择图片文件');
+        return;
+      }
+
+      const imageSrc = await readImageFileAsDataUrl(imageFile);
+      const references = await persistReferenceUploads([
+        {
+          idPrefix: 'upload-ui-design-icon-spec',
+          file: imageFile,
+          fallbackLabel: 'UI设计图标规范',
+          imageSrc,
+        },
+      ]);
+      if (!references) {
+        return;
+      }
+      setGenerateDialog((currentDialog) =>
+        applyGenerationReferenceUpload({
+          dialog: currentDialog,
+          target: 'ui-design-icon-spec',
+          references,
+        }),
+      );
+    },
+    [persistReferenceUploads, setGenerateDialog],
+  );
+
+  const uploadAssetFile = useCallback(
+    async (file: File, options: UploadAssetFileOptions) => {
+      const mediaType = resolveEditorAssetUploadMediaType(file);
+      if (!mediaType) {
+        window.alert('请选择图片、MP3 或 MP4 文件');
+        return;
+      }
+
+      const uploadFolderId = resolveUploadFolderId({
+        assetFolders,
+        requestedFolderId: options.folderId,
+        activeUploadFolderId,
+      });
+      const uploadIndex = options.uploadIndex;
+      let imageDimensions: { width: number; height: number } | null = null;
+      if (mediaType === 'image') {
+        imageDimensions = await probeImageFileDimensions(file).catch(() => null);
+      }
+      const uploadedAsset = createUploadingAssetPlaceholder({
+        uploadIndex,
+        fileName: file.name,
+        folderId: uploadFolderId,
+        mediaType,
+        imageDimensions,
+      });
+      setAssets((currentAssets) => [...currentAssets, uploadedAsset]);
+      setAssetFolders((currentFolders) =>
+        expandUploadFolder({
+          folders: currentFolders,
+          folderId: uploadFolderId,
+        }),
+      );
+
+      let imageSrc = '';
+      let objectKey: string | null = null;
+      let assetObjectId: string | null = null;
+      let durationSeconds: number | undefined;
+      try {
+        if (mediaType === 'image') {
+          imageSrc = await readImageFileAsDataUrl(file);
+        } else {
+          durationSeconds = await probeMediaDurationSeconds(
+            file,
+            mediaType,
+          ).catch(() => undefined);
+          const uploadedMedia = await uploadEditorMediaAssetFile(file, mediaType);
+          imageSrc = uploadedMedia.legacyPublicPath;
+          objectKey = uploadedMedia.objectKey;
+          assetObjectId = uploadedMedia.assetObjectId;
+        }
+        setAssets((currentAssets) =>
+          applyUploadAssetReadSuccess({
+            assets: currentAssets,
+            uploadAssetId: uploadedAsset.id,
+            imageSrc,
+          }),
+        );
+      } catch {
+        setAssets((currentAssets) =>
+          applyUploadAssetReadFailure({
+            assets: currentAssets,
+            uploadAssetId: uploadedAsset.id,
+          }),
+        );
+        return;
+      }
+
+      const nextLayer = createUploadCanvasLayer({
+        uploadIndex,
+        fileName: file.name,
+        imageSrc,
+        mediaType,
+        imageDimensions,
+        durationSeconds,
+        canvasPoint: options.canvasPoint,
+        canvasSize,
+        viewport,
+      });
+
+      if (options.addToCanvas) {
+        appendCanvasLayersWithResources([nextLayer]);
+        selectSingleLayer(nextLayer.id);
+      }
+
+      setAssets((currentAssets) =>
+        applyUploadAssetCreatePending({
+          assets: currentAssets,
+          uploadAssetId: uploadedAsset.id,
+        }),
+      );
+      createEditorAsset({
+        folderId: uploadFolderId,
+        label: uploadedAsset.label,
+        imageSrc,
+        ...(objectKey ? { objectKey } : {}),
+        ...(assetObjectId ? { assetObjectId } : {}),
+        width: uploadedAsset.width,
+        height: uploadedAsset.height,
+        sourceType: 'uploaded',
+        ...(durationSeconds ? { durationSeconds } : {}),
+      })
+        .then((asset) => {
+          setAssets((currentAssets) =>
+            applyPersistedUploadAsset({
+              assets: currentAssets,
+              uploadAssetId: uploadedAsset.id,
+              persistedAsset: asset,
+            }),
+          );
+          if (options.addToCanvas) {
+            setLayers((currentLayers) =>
+              bindUploadLayerToPersistedAsset({
+                layers: currentLayers,
+                layerId: nextLayer.id,
+                persistedAsset: asset,
+              }),
+            );
+          }
+        })
+        .catch((error: unknown) => {
+          const isAuthError = isEditorAuthError(error);
+          if (isAuthError) {
+            openEditorLoginModal();
+          }
+          setAssets((currentAssets) =>
+            applyUploadAssetCreateFailure({
+              assets: currentAssets,
+              uploadAssetId: uploadedAsset.id,
+              message: isAuthError ? '请先登录' : '上传失败',
+            }),
+          );
+        });
+
+      if (mediaType === 'image' && imageSrc) {
+        const uploadedImage = new Image();
+        uploadedImage.onload = () => {
+          const originalWidth =
+            uploadedImage.naturalWidth || uploadedAsset.width;
+          const originalHeight =
+            uploadedImage.naturalHeight || uploadedAsset.height;
+          if (options.addToCanvas) {
+            setLayers((currentLayers) =>
+              currentLayers.map((layer) =>
+                layer.id === nextLayer.id
+                  ? resizeUploadCanvasLayerToImage({
+                      layer,
+                      originalWidth,
+                      originalHeight,
+                      canvasPoint: options.canvasPoint,
+                      canvasSize,
+                      viewport,
+                    })
+                  : layer,
+              ),
+            );
+          }
+          setAssets((currentAssets) =>
+            applyMeasuredUploadAssetSize({
+              assets: currentAssets,
+              uploadAssetId: uploadedAsset.id,
+              originalWidth,
+              originalHeight,
+            }),
+          );
+        };
+        uploadedImage.src = imageSrc;
+      }
+    },
+    [
+      activeUploadFolderId,
+      appendCanvasLayersWithResources,
+      assetFolders,
+      canvasSize.height,
+      canvasSize.width,
+      openEditorLoginModal,
+      selectSingleLayer,
+      setAssetFolders,
+      setAssets,
+      setLayers,
+      viewport.scale,
+      viewport.x,
+      viewport.y,
+    ],
+  );
+
+  const addUploadedFiles = useCallback(
+    (files: FileList | File[], options: UploadFilesOptions = {}) => {
+      const imageFiles = Array.from(files);
+      if (!canAccessProtectedDataRef.current) {
+        openEditorLoginModal(() => {
+          addUploadedFiles(imageFiles, options);
+        });
+        return;
+      }
+      imageFiles.forEach((file, index) => {
+        const uploadIndex = allocateUploadIndex();
+        void uploadAssetFile(file, {
+          ...options,
+          addToCanvas: options.addToCanvas ?? false,
+          uploadIndex,
+          canvasPoint: options.canvasPoint
+            ? {
+                x: options.canvasPoint.x + index * 28,
+                y: options.canvasPoint.y + index * 28,
+              }
+            : undefined,
+        });
+      });
+    },
+    [
+      allocateUploadIndex,
+      openEditorLoginModal,
+      uploadAssetFile,
+    ],
+  );
+
+  const openUploadPicker = useCallback(
+    (target: UploadTarget, options: UploadRequestOptions = {}) => {
+      setUploadTarget(target);
+      uploadRequestOptionsRef.current = options;
+      uploadInputRef.current?.click();
+    },
+    [setUploadTarget],
+  );
+
+  const requestUpload = useCallback(
+    (target: UploadTarget = 'asset', options: UploadRequestOptions = {}) => {
+      if (!canAccessProtectedDataRef.current) {
+        openEditorLoginModal();
+        return;
+      }
+      openUploadPicker(target, options);
+    },
+    [openEditorLoginModal, openUploadPicker],
+  );
+
+  const handleUploadInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const files = event.currentTarget.files;
+      const currentUploadTarget = uploadTargetRef.current;
+      if (files?.length) {
+        if (currentUploadTarget === 'spec-reference') {
+          void addSpecReferenceFiles(files);
+        } else if (currentUploadTarget === 'generation-reference') {
+          void addGenerationReferenceFiles(files);
+        } else if (currentUploadTarget === 'quick-edit-reference') {
+          void addQuickEditReferenceFiles(files);
+        } else if (currentUploadTarget === 'publication-reference') {
+          void addPublicationReferenceFiles(files);
+        } else if (currentUploadTarget === 'video-reference-image') {
+          void addVideoReferenceImageFiles(files);
+        } else if (currentUploadTarget === 'video-reference-video') {
+          void addVideoReferenceVideoFiles(files);
+        } else if (currentUploadTarget === 'video-reference-audio') {
+          void addVideoReferenceAudioFiles(files);
+        } else if (currentUploadTarget === 'character-spec') {
+          void addCharacterSpecReferenceFiles(files);
+        } else if (currentUploadTarget === 'character-reference') {
+          void addCharacterReferenceFiles(files);
+        } else if (currentUploadTarget === 'icon-spec') {
+          void addIconSpecReferenceFiles(files);
+        } else if (currentUploadTarget === 'ui-design-icon-spec') {
+          void addUiDesignSpecReferenceFiles(files);
+        } else {
+          const requestOptions = uploadRequestOptionsRef.current;
+          addUploadedFiles(files, {
+            addToCanvas:
+              requestOptions.addToCanvas ?? activeTool === 'upload',
+          });
+        }
+      }
+      uploadRequestOptionsRef.current = {};
+      setUploadTarget('asset');
+      event.currentTarget.value = '';
+    },
+    [
+      activeTool,
+      addCharacterReferenceFiles,
+      addCharacterSpecReferenceFiles,
+      addGenerationReferenceFiles,
+      addQuickEditReferenceFiles,
+      addPublicationReferenceFiles,
+      addVideoReferenceImageFiles,
+      addVideoReferenceVideoFiles,
+      addVideoReferenceAudioFiles,
+      addSpecReferenceFiles,
+      addIconSpecReferenceFiles,
+      addUiDesignSpecReferenceFiles,
+      addUploadedFiles,
+      setUploadTarget,
+    ],
+  );
+
+  return {
+    uploadInputRef,
+    uploadTarget,
+    setUploadTarget,
+    requestUpload,
+    handleUploadInputChange,
+    addUploadedFiles,
+    addSpecReferenceFiles,
+    addCharacterSpecReferenceFiles,
+    addCharacterReferenceFiles,
+    addGenerationReferenceFiles,
+    addQuickEditReferenceFiles,
+    addPublicationReferenceFiles,
+    addVideoReferenceImageFiles,
+    addVideoReferenceVideoFiles,
+    addVideoReferenceAudioFiles,
+    addIconSpecReferenceFiles,
+    addUiDesignSpecReferenceFiles,
+  };
+}
diff --git a/src/components/image-editor/useImageCanvasViewportControls.test.tsx b/src/components/image-editor/useImageCanvasViewportControls.test.tsx
new file mode 100644
index 000000000..ad23631af
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasViewportControls.test.tsx
@@ -0,0 +1,217 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { useImageCanvasViewportControls } from './useImageCanvasViewportControls';
+
+function createLayer(overrides: Partial<CanvasLayer>): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 100,
+    y: 120,
+    width: 200,
+    height: 100,
+    originalWidth: 200,
+    originalHeight: 100,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function setElementBox(
+  element: HTMLElement,
+  box: { width: number; height: number; left?: number; top?: number },
+) {
+  Object.defineProperty(element, 'clientWidth', {
+    configurable: true,
+    value: box.width,
+  });
+  Object.defineProperty(element, 'clientHeight', {
+    configurable: true,
+    value: box.height,
+  });
+  element.getBoundingClientRect = () =>
+    ({
+      x: box.left ?? 0,
+      y: box.top ?? 0,
+      left: box.left ?? 0,
+      top: box.top ?? 0,
+      right: (box.left ?? 0) + box.width,
+      bottom: (box.top ?? 0) + box.height,
+      width: box.width,
+      height: box.height,
+      toJSON: () => ({}),
+    }) as DOMRect;
+}
+
+function ViewportHarness({
+  captureCanvasHistory = vi.fn(),
+}: {
+  captureCanvasHistory?: () => void;
+}) {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const layers = [
+    createLayer({ id: 'one', x: 0, y: 0, width: 400, height: 300 }),
+    createLayer({ id: 'two', x: 600, y: 100, width: 200, height: 200 }),
+  ];
+  const controls = useImageCanvasViewportControls({
+    canvasViewportRef: viewportRef,
+    layers,
+    captureCanvasHistory,
+  });
+
+  return (
+    <div>
+      <div
+        ref={(element) => {
+          viewportRef.current = element;
+          if (element) {
+            setElementBox(element, { width: 900, height: 640 });
+          }
+        }}
+        data-testid="viewport-element"
+      />
+      <div
+        className="image-canvas-editor__minimap"
+        data-testid="minimap"
+        ref={(element) => {
+          if (element) {
+            setElementBox(element, {
+              left: 20,
+              top: 30,
+              width: 160,
+              height: 120,
+            });
+          }
+        }}
+      />
+      <span data-testid="viewport">
+        {controls.viewport.x.toFixed(2)},{controls.viewport.y.toFixed(2)},
+        {controls.viewport.scale.toFixed(2)}
+      </span>
+      <span data-testid="canvas-size">
+        {controls.canvasSize.width}x{controls.canvasSize.height}
+      </span>
+      <span data-testid="drop-point">
+        {JSON.stringify(controls.getCanvasDropPoint(260, 190))}
+      </span>
+      <span data-testid="world-point">
+        {JSON.stringify(controls.getCanvasPointFromClient(260, 190))}
+      </span>
+      <span data-testid="minimap-count">
+        {controls.minimapModel?.layers.length ?? 0}
+      </span>
+      <button type="button" onClick={() => controls.fitLayers()}>
+        fit
+      </button>
+      <button type="button" onClick={() => controls.updateScaleFromCenter(2)}>
+        zoom center
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          controls.updateViewportFromMinimapDrag(
+            {
+              kind: 'minimap',
+              pointerId: 1,
+              startClientX: 100,
+              startClientY: 100,
+              startViewport: { x: -100, y: -50, scale: 1 },
+              minimapScale: controls.minimapModel?.scale ?? 1,
+              moved: true,
+            },
+            104,
+            103,
+          );
+        }}
+      >
+        minimap drag
+      </button>
+      <button
+        type="button"
+        onClick={() => controls.moveViewportFromMinimapPointer(100, 90)}
+      >
+        minimap click
+      </button>
+    </div>
+  );
+}
+
+describe('useImageCanvasViewportControls', () => {
+  it('owns canvas size, fit view, center zoom and canvas point helpers', () => {
+    const captureCanvasHistory = vi.fn();
+    render(
+      <ViewportHarness captureCanvasHistory={captureCanvasHistory} />,
+    );
+
+    expect(screen.getByTestId('canvas-size').textContent).toBe('900x640');
+    expect(screen.getByTestId('minimap-count').textContent).toBe('2');
+    expect(screen.getByTestId('drop-point').textContent).toBe(
+      '{"x":260,"y":190}',
+    );
+    const worldPoint = JSON.parse(
+      screen.getByTestId('world-point').textContent ?? '{}',
+    ) as { x: number; y: number };
+    expect(worldPoint.x).toBeCloseTo(634.1463);
+    expect(worldPoint.y).toBeCloseTo(146.3415);
+
+    act(() => {
+      screen.getByRole('button', { name: 'fit' }).click();
+    });
+    expect(screen.getByTestId('viewport').textContent).toBe(
+      '50.00,170.00,1.00',
+    );
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      screen.getByRole('button', { name: 'zoom center' }).click();
+    });
+    expect(screen.getByTestId('viewport').textContent).toBe(
+      '-350.00,20.00,2.00',
+    );
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(2);
+  });
+
+  it('handles vertical wheel scroll, ctrl wheel zoom and minimap movement', () => {
+    render(<ViewportHarness />);
+    const viewportElement = screen.getByTestId('viewport-element');
+
+    act(() => {
+      fireEvent.wheel(viewportElement, { deltaY: 120, clientX: 260, clientY: 190 });
+    });
+    expect(screen.getByTestId('viewport').textContent).toBe(
+      '-260.00,-50.00,0.82',
+    );
+
+    act(() => {
+      fireEvent.wheel(viewportElement, {
+        ctrlKey: true,
+        deltaY: -120,
+        clientX: 260,
+        clientY: 190,
+      });
+    });
+    expect(screen.getByTestId('viewport').textContent).toBe(
+      '-312.00,-74.00,0.90',
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: 'minimap drag' }).click();
+    });
+    expect(screen.getByTestId('viewport').textContent).toContain('-');
+
+    const beforeClick = screen.getByTestId('viewport').textContent;
+    act(() => {
+      screen.getByRole('button', { name: 'minimap click' }).click();
+    });
+    expect(screen.getByTestId('viewport').textContent).not.toBe(beforeClick);
+  });
+});
diff --git a/src/components/image-editor/useImageCanvasViewportControls.ts b/src/components/image-editor/useImageCanvasViewportControls.ts
new file mode 100644
index 000000000..30e97ea0b
--- /dev/null
+++ b/src/components/image-editor/useImageCanvasViewportControls.ts
@@ -0,0 +1,258 @@
+import {
+  type RefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import {
+  DEFAULT_CANVAS_SIZE,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasLayer,
+  CanvasViewport,
+  DragState,
+} from './ImageCanvasEditorTypes';
+import {
+  createMinimapModel,
+  fitViewportToLayers,
+  getCanvasDropPoint as resolveCanvasDropPoint,
+  getCanvasPointFromClient as resolveCanvasPointFromClient,
+  getWorldPointFromClient,
+  moveViewportFromMinimapDrag as resolveViewportFromMinimapDrag,
+  moveViewportFromMinimapPointer as resolveViewportFromMinimapPointer,
+  scaleViewportFromScreenPoint,
+  scrollViewportVertically,
+  zoomViewportFromWheel,
+} from './ImageCanvasInteractionModel';
+
+export const DEFAULT_IMAGE_CANVAS_VIEWPORT: CanvasViewport = {
+  x: -260,
+  y: 70,
+  scale: 0.82,
+};
+
+type UseImageCanvasViewportControlsOptions = {
+  canvasViewportRef: RefObject<HTMLDivElement | null>;
+  layers: CanvasLayer[];
+  captureCanvasHistory: () => void;
+};
+
+export function useImageCanvasViewportControls({
+  canvasViewportRef,
+  layers,
+  captureCanvasHistory,
+}: UseImageCanvasViewportControlsOptions) {
+  const [viewport, setViewport] = useState<CanvasViewport>(
+    DEFAULT_IMAGE_CANVAS_VIEWPORT,
+  );
+  const [canvasSize, setCanvasSize] = useState(DEFAULT_CANVAS_SIZE);
+
+  const minimapModel = useMemo(
+    () => createMinimapModel({ layers, viewport, canvasSize }),
+    [canvasSize, layers, viewport],
+  );
+
+  useEffect(() => {
+    const viewportElement = canvasViewportRef.current;
+    if (!viewportElement) {
+      return undefined;
+    }
+
+    const updateCanvasSize = () => {
+      setCanvasSize({
+        width: viewportElement.clientWidth || DEFAULT_CANVAS_SIZE.width,
+        height: viewportElement.clientHeight || DEFAULT_CANVAS_SIZE.height,
+      });
+    };
+
+    updateCanvasSize();
+
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', updateCanvasSize);
+      return () => window.removeEventListener('resize', updateCanvasSize);
+    }
+
+    const observer = new ResizeObserver(updateCanvasSize);
+    observer.observe(viewportElement);
+    return () => observer.disconnect();
+  }, [canvasViewportRef]);
+
+  const updateScaleFromCenter = useCallback(
+    (nextScale: number) => {
+      const viewportElement = canvasViewportRef.current;
+      if (!viewportElement) {
+        captureCanvasHistory();
+        setViewport((currentViewport) =>
+          scaleViewportFromScreenPoint({
+            viewport: currentViewport,
+            nextScale,
+            screenPoint: null,
+          }),
+        );
+        return;
+      }
+
+      const rect = viewportElement.getBoundingClientRect();
+      const centerX = rect.width > 0 ? rect.width / 2 : canvasSize.width / 2;
+      const centerY = rect.height > 0 ? rect.height / 2 : canvasSize.height / 2;
+      captureCanvasHistory();
+      setViewport((currentViewport) =>
+        scaleViewportFromScreenPoint({
+          viewport: currentViewport,
+          nextScale,
+          screenPoint: { x: centerX, y: centerY },
+        }),
+      );
+    },
+    [canvasSize.height, canvasSize.width, canvasViewportRef, captureCanvasHistory],
+  );
+
+  const fitLayers = useCallback(
+    (targetLayers: CanvasLayer[] = layers) => {
+      const nextViewport = fitViewportToLayers({
+        layers: targetLayers,
+        canvasSize,
+      });
+      if (!nextViewport) {
+        return;
+      }
+
+      captureCanvasHistory();
+      setViewport(nextViewport);
+    },
+    [captureCanvasHistory, canvasSize, layers],
+  );
+
+  const resolveCanvasPoint = useCallback(
+    (clientX: number, clientY: number) => {
+      const rect = canvasViewportRef.current?.getBoundingClientRect() ?? null;
+      return resolveCanvasPointFromClient({ clientX, clientY, rect });
+    },
+    [canvasViewportRef],
+  );
+
+  const getCanvasDropPoint = useCallback(
+    (clientX: number, clientY: number) =>
+      resolveCanvasDropPoint({
+        clientX,
+        clientY,
+        rect: canvasViewportRef.current?.getBoundingClientRect() ?? null,
+        canvasSize,
+      }),
+    [canvasSize, canvasViewportRef],
+  );
+
+  const getCanvasPointFromClient = useCallback(
+    (clientX: number, clientY: number) =>
+      getWorldPointFromClient({
+        clientX,
+        clientY,
+        rect: canvasViewportRef.current?.getBoundingClientRect() ?? null,
+        viewport,
+      }),
+    [canvasViewportRef, viewport],
+  );
+
+  const moveViewportFromMinimapPointer = useCallback(
+    (clientX: number, clientY: number) => {
+      if (!minimapModel) {
+        return;
+      }
+      const minimapElement = document.querySelector(
+        '.image-canvas-editor__minimap',
+      ) as HTMLElement | null;
+      const rect = minimapElement?.getBoundingClientRect();
+      if (!rect) {
+        return;
+      }
+      setViewport((currentViewport) =>
+        resolveViewportFromMinimapPointer({
+          viewport: currentViewport,
+          canvasSize,
+          minimapModel,
+          pointer: {
+            x: clientX - rect.left,
+            y: clientY - rect.top,
+          },
+        }),
+      );
+    },
+    [canvasSize, minimapModel],
+  );
+
+  const updateViewportFromMinimapDrag = useCallback(
+    (
+      dragState: Extract<DragState, { kind: 'minimap' }>,
+      clientX: number,
+      clientY: number,
+    ) => {
+      setViewport(
+        resolveViewportFromMinimapDrag(dragState, {
+          x: clientX,
+          y: clientY,
+        }),
+      );
+    },
+    [],
+  );
+
+  const handleNativeWheel = useCallback(
+    (event: WheelEvent) => {
+      event.preventDefault();
+      const viewportElement = canvasViewportRef.current;
+      if (!viewportElement) {
+        return;
+      }
+
+      if (!event.ctrlKey && !event.metaKey) {
+        setViewport((currentViewport) =>
+          scrollViewportVertically(currentViewport, event.deltaY),
+        );
+        return;
+      }
+
+      const rect = viewportElement.getBoundingClientRect();
+      const screenPoint = {
+        x: event.clientX - rect.left,
+        y: event.clientY - rect.top,
+      };
+      setViewport((currentViewport) =>
+        zoomViewportFromWheel({
+          viewport: currentViewport,
+          deltaY: event.deltaY,
+          screenPoint,
+        }),
+      );
+    },
+    [canvasViewportRef],
+  );
+
+  useEffect(() => {
+    const viewportElement = canvasViewportRef.current;
+    if (!viewportElement) {
+      return undefined;
+    }
+    viewportElement.addEventListener('wheel', handleNativeWheel, {
+      passive: false,
+    });
+    return () => {
+      viewportElement.removeEventListener('wheel', handleNativeWheel);
+    };
+  }, [canvasViewportRef, handleNativeWheel]);
+
+  return {
+    viewport,
+    setViewport,
+    canvasSize,
+    minimapModel,
+    updateScaleFromCenter,
+    fitLayers,
+    resolveCanvasPoint,
+    getCanvasDropPoint,
+    getCanvasPointFromClient,
+    moveViewportFromMinimapPointer,
+    updateViewportFromMinimapDrag,
+  };
+}
diff --git a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
index ba5eccb4f..d060c9c6e 100644
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -1,3 +1,5 @@
+import { Loader2 } from 'lucide-react';
+
 import { AnimatePresence, motion } from 'motion/react';
 import {
   type Dispatch,
@@ -534,6 +536,7 @@ import {
   PlatformEntryHomeView,
   type PlatformHomeTab,
 } from './PlatformEntryHomeView';
+import { PlatformProfileReferralModal } from './PlatformProfileReferralModal';
 import { usePlatformDesktopLayout } from './platformEntryResponsive';
 import {
   buildCreationHubFallbackItems,
@@ -1294,6 +1297,27 @@ const CustomWorldGenerationView = lazy(async () => {
   };
 });
 
+const ImageCanvasEditorView = lazy(async () => {
+  const module = await import('../image-editor/ImageCanvasEditorView');
+  return {
+    default: module.ImageCanvasEditorView,
+  };
+});
+
+const ProjectGalleryView = lazy(async () => {
+  const module = await import('../project/ProjectGalleryView');
+  return {
+    default: module.ProjectGalleryView,
+  };
+});
+
+const CreationLandingView = lazy(async () => {
+  const module = await import('../creation-home/CreationLandingView');
+  return {
+    default: module.CreationLandingView,
+  };
+});
+
 const UnifiedCreationWorkspace = lazy(async () => {
   const module = await import('../unified-creation/UnifiedCreationWorkspace');
   return {
@@ -1629,6 +1653,8 @@ export function PlatformEntryFlowShellImpl({
       : 'platform-theme--light';
   const isDesktopLayout = usePlatformDesktopLayout();
   const [showCreationTypeModal, setShowCreationTypeModal] = useState(false);
+  const [isCreationCommunityOpen, setIsCreationCommunityOpen] =
+    useState(false);
   const [draftGenerationPointNotice, setDraftGenerationPointNotice] =
     useState<DraftGenerationPointNotice | null>(null);
   const [selectedDetailEntry, setSelectedDetailEntry] =
@@ -3606,6 +3632,24 @@ export function PlatformEntryFlowShellImpl({
   ]);
 
   const openCreationTypePicker = useCallback(() => {
+    setSelectionStage('creation-home');
+  }, [setSelectionStage]);
+
+  const openProjectGallery = useCallback(() => {
+    setSelectionStage('project');
+  }, [setSelectionStage]);
+
+  const openCreationCommunity = useCallback(() => {
+    setIsCreationCommunityOpen(true);
+  }, []);
+
+  const openEditorProject = useCallback((projectId: string) => {
+    setSelectionStage('image-editor', {
+      path: `/editor/canvas?projectid=${encodeURIComponent(projectId)}`,
+    });
+  }, [setSelectionStage]);
+
+  const openCreationTypeModal = useCallback(() => {
     if (!prepareCreationLaunch()) {
       return;
     }
@@ -5118,16 +5162,22 @@ export function PlatformEntryFlowShellImpl({
       () => pendingPlatformTaskCompletionDialog,
       [pendingPlatformTaskCompletionDialog],
     );
-  const activePlatformTaskCompletionDialog = resolveActivePlatformDialog(
-    currentPlatformTaskCompletionDialog,
-    dismissedPlatformTaskCompletionDialogKey,
-    buildPlatformTaskCompletionDialogDismissKey,
-  );
-  const activePlatformErrorDialog = resolveActivePlatformDialog(
-    currentPlatformErrorDialog,
-    dismissedPlatformErrorDialogKey,
-    buildPlatformErrorDialogDismissKey,
-  );
+  const activePlatformTaskCompletionDialog =
+    selectionStage === 'image-editor'
+      ? null
+      : resolveActivePlatformDialog(
+          currentPlatformTaskCompletionDialog,
+          dismissedPlatformTaskCompletionDialogKey,
+          buildPlatformTaskCompletionDialogDismissKey,
+        );
+  const activePlatformErrorDialog =
+    selectionStage === 'image-editor'
+      ? null
+      : resolveActivePlatformDialog(
+          currentPlatformErrorDialog,
+          dismissedPlatformErrorDialogKey,
+          buildPlatformErrorDialogDismissKey,
+        );
   const closePlatformErrorDialog = useCallback(() => {
     if (!currentPlatformErrorDialog) {
       return;
@@ -15188,10 +15238,218 @@ export function PlatformEntryFlowShellImpl({
     'works-only',
     '正在加载草稿列表...',
   );
+  const creationLandingContent = (
+    <Suspense fallback={<LazyPanelFallback label="正在加载创作主页..." />}>
+      <CreationLandingView
+        onOpenProject={openEditorProject}
+        onOpenProjects={openProjectGallery}
+        onOpenCommunity={openCreationCommunity}
+        publicGalleryEntries={[
+          ...featuredGalleryEntries,
+          ...latestGalleryEntries,
+        ]}
+      />
+    </Suspense>
+  );
+  const projectGalleryContent = (
+    <Suspense fallback={<LazyPanelFallback label="正在加载项目..." />}>
+      <ProjectGalleryView
+        onOpenProject={openEditorProject}
+        onReturnToMainSite={() => {
+          platformBootstrap.setPlatformTab('home');
+          setSelectionStage('platform');
+          pushAppHistoryPath('/');
+        }}
+      />
+    </Suspense>
+  );
+  const handlePlatformHomeTabChange = useCallback(
+    (tab: PlatformHomeTab) => {
+      platformBootstrap.setPlatformTab(tab);
+      if (
+        (selectionStage === 'creation-home' && tab !== 'create') ||
+        selectionStage === 'project'
+      ) {
+        setSelectionStage('platform');
+        pushAppHistoryPath('/');
+      }
+    },
+    [platformBootstrap, selectionStage, setSelectionStage],
+  );
+  const platformHomeView = (
+    <PlatformEntryHomeView
+      activeTab={
+        selectionStage === 'creation-home' || selectionStage === 'project'
+          ? 'create'
+          : platformBootstrap.platformTab
+      }
+      activeDesktopNavTab={selectionStage === 'project' ? 'projects' : undefined}
+      allowHiddenActiveTab={
+        selectionStage === 'creation-home' || selectionStage === 'project'
+      }
+      onTabChange={handlePlatformHomeTabChange}
+      hasSavedGame={hasSavedGame}
+      savedSnapshot={savedSnapshot}
+      saveEntries={platformBootstrap.saveEntries}
+      saveError={platformBootstrap.saveError}
+      featuredEntries={featuredGalleryEntries}
+      latestEntries={latestGalleryEntries}
+      myEntries={platformBootstrap.savedCustomWorldEntries}
+      historyEntries={platformBootstrap.historyEntries}
+      profileDashboard={platformBootstrap.profileDashboard}
+      isLoadingPlatform={platformBootstrap.isLoadingPlatform}
+      isLoadingDashboard={platformBootstrap.isLoadingDashboard}
+      hasUnreadDraftUpdate={hasUnreadDraftUpdates}
+      profileTaskRefreshKey={profileTaskRefreshKey}
+      profileGenerationQueueStatus={profileExternalGenerationQueueStatus}
+      isDesktopLayout={isDesktopLayout}
+      isResumingSaveWorldKey={platformBootstrap.isResumingSaveWorldKey}
+      platformError={
+        platformBootstrap.isLoadingPlatform
+          ? null
+          : (platformBootstrapErrorForDisplay ??
+            sessionController.agentWorkspaceRestoreError)
+      }
+      dashboardError={
+        platformBootstrap.isLoadingDashboard
+          ? null
+          : platformBootstrap.dashboardError
+      }
+      createTabContent={
+        selectionStage === 'project'
+          ? projectGalleryContent
+          : selectionStage === 'creation-home'
+            ? creationLandingContent
+            : creationStartContent
+      }
+      draftTabContent={draftHubContent}
+      onContinueGame={handleContinueGame}
+      onResumeSave={(entry) => {
+        if (
+          (entry.worldType ?? '').toLowerCase() === 'puzzle' ||
+          entry.worldKey.startsWith('puzzle:')
+        ) {
+          void resumePuzzleSaveArchive(entry);
+          return;
+        }
+        void platformBootstrap.handleResumeSaveEntry(entry);
+      }}
+      onOpenCreateWorld={openCreationTypeModal}
+      onOpenCreateTypePicker={openCreationTypePicker}
+      onOpenGalleryDetail={openPublicGalleryDetail}
+      onOpenChildMotionDemo={startChildMotionDemo}
+      onOpenBabyLoveDrawing={startBabyLoveDrawingRuntime}
+      onOpenRecommendGalleryDetail={openRecommendGalleryDetail}
+      recommendRuntimeContent={recommendRuntimeContent}
+      activeRecommendEntryKey={activeRecommendEntryKey}
+      isRecommendRuntimeReady={isActiveRecommendRuntimeReady}
+      isStartingRecommendEntry={
+        isStartingRecommendEntry ||
+        isBigFishBusy ||
+        (isPuzzleBusy &&
+          !(activeRecommendRuntimeKind === 'puzzle' && puzzleRun)) ||
+        (isPuzzleClearBusy &&
+          !(
+            activeRecommendRuntimeKind === 'puzzle-clear' &&
+            puzzleClearRun
+          )) ||
+        isMatch3DBusy ||
+        isSquareHoleBusy ||
+        isVisualNovelBusy ||
+        isWoodenFishBusy
+      }
+      recommendRuntimeError={activeRecommendRuntimeError}
+      onSelectNextRecommendEntry={(activeEntryKey) =>
+        selectAdjacentRecommendRuntimeEntry(1, activeEntryKey)
+      }
+      onSelectPreviousRecommendEntry={(activeEntryKey) =>
+        selectAdjacentRecommendRuntimeEntry(-1, activeEntryKey)
+      }
+      onLikeRecommendEntry={(entry) => {
+        likePublicWork(entry);
+      }}
+      onShareRecommendEntry={(entry) => {
+        openRecommendShareModal(entry);
+      }}
+      onRemixRecommendEntry={(entry) => {
+        remixPublicWork(entry);
+      }}
+      onOpenLibraryDetail={(entry) => {
+        runProtectedAction(() => {
+          void detailNavigation.openLibraryDetail(entry);
+        });
+      }}
+      onDeleteLibraryEntry={(entry) => {
+        handleDeleteLibraryEntry(entry);
+      }}
+      deletingLibraryEntryId={deletingCreationWorkId}
+      onSearchPublicCode={(keyword) => {
+        void handlePublicCodeSearch(keyword);
+      }}
+      isSearchingPublicCode={isSearchingPublicCode}
+      profilePlayStats={profilePlayStats}
+      isProfilePlayStatsOpen={isProfilePlayStatsOpen}
+      isProfilePlayStatsLoading={isProfilePlayStatsLoading}
+      profilePlayStatsError={profilePlayStatsError}
+      onCloseProfilePlayStats={() => {
+        setIsProfilePlayStatsOpen(false);
+      }}
+      onOpenPlayedWork={openPlayedWork}
+      onOpenFeedback={openProfileFeedback}
+      onOpenProjects={openProjectGallery}
+      onOpenProfileDashboardCard={(cardKey) => {
+        if (cardKey === 'playedWorks') {
+          openProfilePlayedWorks();
+          return;
+        }
+        if (platformBootstrap.dashboardError) {
+          void platformBootstrap.refreshProfileDashboard();
+        }
+      }}
+      onRechargeSuccess={platformBootstrap.refreshProfileDashboard}
+    />
+  );
 
   return (
     <>
       <AnimatePresence mode="wait">
+        {selectionStage === 'image-editor' && (
+          <motion.div
+            key="image-editor"
+            initial={{ opacity: 0, y: 12 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -12 }}
+            className="image-editor-stage-shell flex h-full min-h-0 min-w-0 flex-col overflow-hidden"
+          >
+            <Suspense
+              fallback={<LazyPanelFallback label="正在加载编辑器..." />}
+            >
+              <ImageCanvasEditorView />
+            </Suspense>
+          </motion.div>
+        )}
+        {selectionStage === 'creation-home' && (
+          <motion.div
+            key="creation-home"
+            initial={{ opacity: 0, y: 12 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -12 }}
+            className="creation-home-stage flex h-full min-h-0 min-w-0 flex-col overflow-hidden"
+          >
+            {platformHomeView}
+          </motion.div>
+        )}
+        {selectionStage === 'project' && (
+          <motion.div
+            key="project-gallery"
+            initial={{ opacity: 0, y: 12 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -12 }}
+            className="creation-home-stage flex h-full min-h-0 min-w-0 flex-col overflow-hidden"
+          >
+            {platformHomeView}
+          </motion.div>
+        )}
         {selectionStage === 'platform' && (
           <motion.div
             key="platform-home"
@@ -15200,122 +15458,7 @@ export function PlatformEntryFlowShellImpl({
             exit={{ opacity: 0, y: -12 }}
             className="flex h-full min-h-0 min-w-0 flex-col overflow-hidden"
           >
-            <PlatformEntryHomeView
-              activeTab={platformBootstrap.platformTab}
-              onTabChange={platformBootstrap.setPlatformTab}
-              hasSavedGame={hasSavedGame}
-              savedSnapshot={savedSnapshot}
-              saveEntries={platformBootstrap.saveEntries}
-              saveError={platformBootstrap.saveError}
-              featuredEntries={featuredGalleryEntries}
-              latestEntries={latestGalleryEntries}
-              myEntries={platformBootstrap.savedCustomWorldEntries}
-              historyEntries={platformBootstrap.historyEntries}
-              profileDashboard={platformBootstrap.profileDashboard}
-              isLoadingPlatform={platformBootstrap.isLoadingPlatform}
-              isLoadingDashboard={platformBootstrap.isLoadingDashboard}
-              hasUnreadDraftUpdate={hasUnreadDraftUpdates}
-              profileTaskRefreshKey={profileTaskRefreshKey}
-              profileGenerationQueueStatus={profileExternalGenerationQueueStatus}
-              isDesktopLayout={isDesktopLayout}
-              isResumingSaveWorldKey={platformBootstrap.isResumingSaveWorldKey}
-              platformError={
-                platformBootstrap.isLoadingPlatform
-                  ? null
-                  : (platformBootstrapErrorForDisplay ??
-                    sessionController.agentWorkspaceRestoreError)
-              }
-              dashboardError={
-                platformBootstrap.isLoadingDashboard
-                  ? null
-                  : platformBootstrap.dashboardError
-              }
-              createTabContent={creationStartContent}
-              draftTabContent={draftHubContent}
-              onContinueGame={handleContinueGame}
-              onResumeSave={(entry) => {
-                if (
-                  (entry.worldType ?? '').toLowerCase() === 'puzzle' ||
-                  entry.worldKey.startsWith('puzzle:')
-                ) {
-                  void resumePuzzleSaveArchive(entry);
-                  return;
-                }
-                void platformBootstrap.handleResumeSaveEntry(entry);
-              }}
-              onOpenCreateWorld={openCreationTypePicker}
-              onOpenCreateTypePicker={openCreationTypePicker}
-              onOpenGalleryDetail={openPublicGalleryDetail}
-              onOpenChildMotionDemo={startChildMotionDemo}
-              onOpenBabyLoveDrawing={startBabyLoveDrawingRuntime}
-              onOpenRecommendGalleryDetail={openRecommendGalleryDetail}
-              recommendRuntimeContent={recommendRuntimeContent}
-              activeRecommendEntryKey={activeRecommendEntryKey}
-              isRecommendRuntimeReady={isActiveRecommendRuntimeReady}
-              isStartingRecommendEntry={
-                isStartingRecommendEntry ||
-                isBigFishBusy ||
-                (isPuzzleBusy &&
-                  !(activeRecommendRuntimeKind === 'puzzle' && puzzleRun)) ||
-                (isPuzzleClearBusy &&
-                  !(
-                    activeRecommendRuntimeKind === 'puzzle-clear' &&
-                    puzzleClearRun
-                  )) ||
-                isMatch3DBusy ||
-                isSquareHoleBusy ||
-                isVisualNovelBusy ||
-                isWoodenFishBusy
-              }
-              recommendRuntimeError={activeRecommendRuntimeError}
-              onSelectNextRecommendEntry={(activeEntryKey) =>
-                selectAdjacentRecommendRuntimeEntry(1, activeEntryKey)
-              }
-              onSelectPreviousRecommendEntry={(activeEntryKey) =>
-                selectAdjacentRecommendRuntimeEntry(-1, activeEntryKey)
-              }
-              onLikeRecommendEntry={(entry) => {
-                likePublicWork(entry);
-              }}
-              onShareRecommendEntry={(entry) => {
-                openRecommendShareModal(entry);
-              }}
-              onRemixRecommendEntry={(entry) => {
-                remixPublicWork(entry);
-              }}
-              onOpenLibraryDetail={(entry) => {
-                runProtectedAction(() => {
-                  void detailNavigation.openLibraryDetail(entry);
-                });
-              }}
-              onDeleteLibraryEntry={(entry) => {
-                handleDeleteLibraryEntry(entry);
-              }}
-              deletingLibraryEntryId={deletingCreationWorkId}
-              onSearchPublicCode={(keyword) => {
-                void handlePublicCodeSearch(keyword);
-              }}
-              isSearchingPublicCode={isSearchingPublicCode}
-              profilePlayStats={profilePlayStats}
-              isProfilePlayStatsOpen={isProfilePlayStatsOpen}
-              isProfilePlayStatsLoading={isProfilePlayStatsLoading}
-              profilePlayStatsError={profilePlayStatsError}
-              onCloseProfilePlayStats={() => {
-                setIsProfilePlayStatsOpen(false);
-              }}
-              onOpenPlayedWork={openPlayedWork}
-              onOpenFeedback={openProfileFeedback}
-              onOpenProfileDashboardCard={(cardKey) => {
-                if (cardKey === 'playedWorks') {
-                  openProfilePlayedWorks();
-                  return;
-                }
-                if (platformBootstrap.dashboardError) {
-                  void platformBootstrap.refreshProfileDashboard();
-                }
-              }}
-              onRechargeSuccess={platformBootstrap.refreshProfileDashboard}
-            />
+            {platformHomeView}
           </motion.div>
         )}
 
@@ -17713,6 +17856,22 @@ export function PlatformEntryFlowShellImpl({
         overlayClassName={`platform-theme ${platformThemeClass} !items-center`}
         panelClassName="platform-remap-surface rounded-[1.5rem]"
       />
+      {isCreationCommunityOpen ? (
+        <PlatformProfileReferralModal
+          panel="community"
+          center={null}
+          isLoading={false}
+          isSubmittingRedeem={false}
+          redeemCode=""
+          copyInviteState="idle"
+          error={null}
+          success={null}
+          onClose={() => setIsCreationCommunityOpen(false)}
+          onCopyInvite={() => undefined}
+          onRedeemCodeChange={() => undefined}
+          onSubmitRedeemCode={() => undefined}
+        />
+      ) : null}
       <PlatformAcknowledgeStatusDialog
         open={Boolean(workNotFoundRecoveryDialog)}
         status="error"
diff --git a/src/components/platform-entry/PlatformProfileApiKeysModal.tsx b/src/components/platform-entry/PlatformProfileApiKeysModal.tsx
new file mode 100644
index 000000000..05a8063a6
--- /dev/null
+++ b/src/components/platform-entry/PlatformProfileApiKeysModal.tsx
@@ -0,0 +1,305 @@
+import { KeyRound, ShieldCheck, Trash2 } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import type {
+  ExternalApiKeyCreateResponse,
+  ExternalApiKeyProfile,
+} from '../../../packages/shared/src/contracts/runtime';
+import {
+  createRpgProfileExternalApiKey,
+  listRpgProfileExternalApiKeys,
+  revokeRpgProfileExternalApiKey,
+} from '../../services/rpg-entry/rpgProfileClient';
+import { CopyFeedbackButton } from '../common/CopyFeedbackButton';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformAsyncStatePanel } from '../common/PlatformAsyncStatePanel';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import { PlatformProfileContentRow } from '../common/PlatformProfileContentRow';
+import { PlatformProfileSkeletonList } from '../common/PlatformProfileSkeletonList';
+import { PlatformProfileSummaryHeader } from '../common/PlatformProfileSummaryHeader';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { useCopyFeedback } from '../common/useCopyFeedback';
+import { formatPlatformWorldTime } from '../rpg-entry/rpgEntryWorldPresentation';
+import { PlatformProfileSecondaryModalShell } from './PlatformProfileModalShell';
+
+type PlatformProfileApiKeysModalProps = {
+  onClose: () => void;
+};
+
+function isActiveExternalApiKey(key: ExternalApiKeyProfile) {
+  return !key.revokedAt;
+}
+
+function buildApiKeyTimeLabel(value: string | null) {
+  return value ? formatPlatformWorldTime(value) : '尚未使用';
+}
+
+function buildApiKeyScopeLabel(scopes: string[]) {
+  return scopes.length > 0 ? scopes.join(' / ') : '默认权限';
+}
+
+/**
+ * 开发者 API Key 管理弹窗。
+ * 明文 Key 只保留在本次创建后的组件状态里，关闭弹窗后即丢弃。
+ */
+export function PlatformProfileApiKeysModal({
+  onClose,
+}: PlatformProfileApiKeysModalProps) {
+  const [keys, setKeys] = useState<ExternalApiKeyProfile[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [nameInput, setNameInput] = useState('外部 API Key');
+  const [createdKey, setCreatedKey] =
+    useState<ExternalApiKeyCreateResponse | null>(null);
+  const [isCreating, setIsCreating] = useState(false);
+  const [revokingKeyId, setRevokingKeyId] = useState<string | null>(null);
+  const { copyState, copyText } = useCopyFeedback();
+
+  const activeKeys = useMemo(
+    () => keys.filter(isActiveExternalApiKey),
+    [keys],
+  );
+  const shouldShowBlockingError = Boolean(error && !isLoading && keys.length === 0);
+
+  const loadKeys = useCallback(() => {
+    setIsLoading(true);
+    setError(null);
+    void listRpgProfileExternalApiKeys()
+      .then((response) => {
+        setKeys(response.keys);
+      })
+      .catch((loadError: unknown) => {
+        setError(loadError instanceof Error ? loadError.message : '读取 API Key 失败');
+      })
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  useEffect(() => {
+    loadKeys();
+  }, [loadKeys]);
+
+  const createKey = useCallback(() => {
+    if (isCreating) {
+      return;
+    }
+    setIsCreating(true);
+    setError(null);
+    setCreatedKey(null);
+    void createRpgProfileExternalApiKey(nameInput)
+      .then((response) => {
+        setCreatedKey(response);
+        setKeys((current) => [
+          response.key,
+          ...current.filter((key) => key.keyId !== response.key.keyId),
+        ]);
+        setNameInput('外部 API Key');
+      })
+      .catch((createError: unknown) => {
+        setError(
+          createError instanceof Error ? createError.message : '创建 API Key 失败',
+        );
+      })
+      .finally(() => setIsCreating(false));
+  }, [isCreating, nameInput]);
+
+  const revokeKey = useCallback((keyId: string) => {
+    setRevokingKeyId(keyId);
+    setError(null);
+    void revokeRpgProfileExternalApiKey(keyId)
+      .then((response) => {
+        setKeys((current) =>
+          current.map((key) =>
+            key.keyId === response.key.keyId ? response.key : key,
+          ),
+        );
+        setCreatedKey((current) =>
+          current?.key.keyId === response.key.keyId ? null : current,
+        );
+      })
+      .catch((revokeError: unknown) => {
+        setError(
+          revokeError instanceof Error ? revokeError.message : '撤销 API Key 失败',
+        );
+      })
+      .finally(() => setRevokingKeyId(null));
+  }, []);
+
+  return (
+    <PlatformProfileSecondaryModalShell
+      title="开发者 API Key"
+      onClose={onClose}
+      closeLabel="关闭开发者 API Key"
+      closeButtonClassName="bg-white/80"
+      panelClassName="relative !max-h-[min(92vh,44rem)] !max-w-[34rem] bg-[linear-gradient(180deg,#f8fbff_0%,#ffffff_42%,#f8fafc_100%)] text-zinc-950 shadow-2xl !rounded-[1.35rem] sm:!rounded-[1.35rem]"
+      contentClassName="relative max-h-[min(92vh,44rem)] overflow-y-auto px-4 pb-5 pt-4 sm:px-5"
+    >
+      <PlatformProfileSummaryHeader
+        kicker="OPENAPI"
+        title="开发者 API Key"
+        badge={
+          <span className="inline-flex items-center gap-1.5 rounded-full bg-white/76 px-3 py-1 text-xs font-black text-sky-700 shadow-sm ring-1 ring-sky-100">
+            <ShieldCheck className="h-3.5 w-3.5" />
+            {activeKeys.length} 个可用
+          </span>
+        }
+      />
+
+      <div className="mt-5 rounded-[1.1rem] border border-sky-100 bg-white/82 p-3 shadow-sm">
+        <div className="flex items-end gap-2">
+          <label className="min-w-0 flex-1">
+            <span className="mb-1.5 block text-xs font-black text-zinc-500">
+              名称
+            </span>
+            <PlatformTextField
+              value={nameInput}
+              density="compact"
+              tone="sky"
+              onChange={(event) => setNameInput(event.target.value)}
+            />
+          </label>
+          <PlatformActionButton
+            surface="profile"
+            size="sm"
+            className="shrink-0"
+            disabled={isCreating}
+            onClick={createKey}
+          >
+            <KeyRound className="h-4 w-4" />
+            {isCreating ? '创建中' : '创建'}
+          </PlatformActionButton>
+        </div>
+      </div>
+
+      {createdKey ? (
+        <PlatformStatusMessage
+          tone="success"
+          surface="profile"
+          size="sm"
+          className="mt-4 rounded-2xl font-semibold"
+        >
+          <div className="text-xs font-black text-emerald-700">新 Key</div>
+          <div className="mt-2 break-all rounded-xl bg-white/80 px-3 py-2 font-mono text-[12px] text-zinc-800">
+            {createdKey.apiKey}
+          </div>
+          <CopyFeedbackButton
+            state={copyState}
+            idleLabel="复制 Key"
+            actionSurface="profile"
+            actionTone="primary"
+            actionSize="xs"
+            className="mt-3"
+            onClick={() => void copyText(createdKey.apiKey)}
+          />
+        </PlatformStatusMessage>
+      ) : null}
+
+      <PlatformAsyncStatePanel
+        errorState={
+          shouldShowBlockingError ? (
+            <PlatformStatusMessage
+              tone="error"
+              surface="profile"
+              size="xs"
+              className="mt-4 rounded-2xl font-semibold"
+            >
+              <div>{error}</div>
+              <PlatformActionButton
+                surface="profile"
+                size="xs"
+                className="mt-3"
+                onClick={loadKeys}
+              >
+                重新加载
+              </PlatformActionButton>
+            </PlatformStatusMessage>
+          ) : null
+        }
+        isLoading={isLoading}
+        loadingState={
+          <PlatformProfileSkeletonList
+            count={3}
+            containerClassName="mt-5 space-y-3"
+            itemClassName="h-20 rounded-2xl bg-white/70"
+          />
+        }
+        isEmpty={keys.length === 0}
+        emptyState={
+          <PlatformEmptyState
+            surface="subpanel"
+            size="inline"
+            className="mt-5 py-8"
+          >
+            暂无 API Key
+          </PlatformEmptyState>
+        }
+      >
+        {error ? (
+          <PlatformStatusMessage
+            tone="error"
+            surface="profile"
+            size="xs"
+            className="mb-3 rounded-2xl font-semibold"
+          >
+            {error}
+          </PlatformStatusMessage>
+        ) : null}
+        <div className="mt-5 space-y-2.5">
+          {keys.map((key) => {
+            const isActive = isActiveExternalApiKey(key);
+            const isRevoking = revokingKeyId === key.keyId;
+            return (
+              <PlatformProfileContentRow
+                key={key.keyId}
+                surface="flat"
+                radius="xs"
+                padding="none"
+                className="flex items-start justify-between gap-3 px-3 py-3 shadow-sm"
+              >
+                <div className="min-w-0">
+                  <div className="flex min-w-0 items-center gap-2">
+                    <span className="truncate text-sm font-black text-zinc-900">
+                      {key.name}
+                    </span>
+                    <span
+                      className={`shrink-0 rounded-full px-2 py-0.5 text-[10px] font-black ${
+                        isActive
+                          ? 'bg-emerald-50 text-emerald-700'
+                          : 'bg-zinc-100 text-zinc-500'
+                      }`}
+                    >
+                      {isActive ? '可用' : '已撤销'}
+                    </span>
+                  </div>
+                  <div className="mt-1 font-mono text-xs font-semibold text-zinc-500">
+                    {key.keyPrefix}...
+                  </div>
+                  <div className="mt-2 text-[11px] font-semibold text-zinc-400">
+                    {buildApiKeyScopeLabel(key.scopes)}
+                  </div>
+                  <div className="mt-1 text-[11px] font-semibold text-zinc-400">
+                    创建 {buildApiKeyTimeLabel(key.createdAt)} · 最近使用{' '}
+                    {buildApiKeyTimeLabel(key.lastUsedAt)}
+                  </div>
+                </div>
+                {isActive ? (
+                  <PlatformActionButton
+                    surface="profile"
+                    tone="danger"
+                    size="xs"
+                    className="shrink-0"
+                    disabled={isRevoking}
+                    onClick={() => revokeKey(key.keyId)}
+                  >
+                    <Trash2 className="h-3.5 w-3.5" />
+                    {isRevoking ? '撤销中' : '撤销'}
+                  </PlatformActionButton>
+                ) : null}
+              </PlatformProfileContentRow>
+            );
+          })}
+        </div>
+      </PlatformAsyncStatePanel>
+    </PlatformProfileSecondaryModalShell>
+  );
+}
diff --git a/src/components/platform-entry/platformEntryTypes.ts b/src/components/platform-entry/platformEntryTypes.ts
index 5a24528e5..6e678d9fa 100644
--- a/src/components/platform-entry/platformEntryTypes.ts
+++ b/src/components/platform-entry/platformEntryTypes.ts
@@ -1,6 +1,4 @@
-import type {
-  CustomWorldAgentSessionSnapshot,
-} from '../../../packages/shared/src/contracts/customWorldAgent';
+import type { CustomWorldAgentSessionSnapshot } from '../../../packages/shared/src/contracts/customWorldAgent';
 import type { RpgCreationResultView } from '../../../packages/shared/src/contracts/rpgCreationResultView';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
 import type { CustomWorldProfile } from '../../types';
@@ -15,6 +13,9 @@ export type CustomWorldRuntimeLaunchOptions = {
 
 export type SelectionStage =
   | 'platform'
+  | 'creation-home'
+  | 'project'
+  | 'image-editor'
   | 'profile-feedback'
   | 'work-detail'
   | 'detail'
@@ -70,7 +71,10 @@ export type SelectionStage =
 
 export type CustomWorldGenerationViewSource = 'agent-draft-foundation' | null;
 
-export type CustomWorldResultViewSource = 'saved-profile' | 'agent-draft' | null;
+export type CustomWorldResultViewSource =
+  | 'saved-profile'
+  | 'agent-draft'
+  | null;
 
 export type CustomWorldAutoSaveState = 'idle' | 'saving' | 'saved' | 'error';
 
@@ -82,7 +86,10 @@ export type SyncedAgentDraftResult = {
 
 export type PlatformEntryFlowShellProps = {
   selectionStage: SelectionStage;
-  setSelectionStage: (stage: SelectionStage) => void;
+  setSelectionStage: (
+    stage: SelectionStage,
+    options?: { path?: string },
+  ) => void;
   initialPublicWorkCode?: string | null;
   hasSavedGame: boolean;
   savedSnapshot: HydratedSavedGameSnapshot | null;
diff --git a/src/components/platform-entry/platformSelectionStageModel.ts b/src/components/platform-entry/platformSelectionStageModel.ts
index e14ad152e..49ed1ad84 100644
--- a/src/components/platform-entry/platformSelectionStageModel.ts
+++ b/src/components/platform-entry/platformSelectionStageModel.ts
@@ -2,6 +2,9 @@ import type { SelectionStage } from './platformEntryTypes';
 
 const PROTECTED_DATA_LOSS_STABLE_STAGE_BY_STAGE = {
   platform: true,
+  'creation-home': true,
+  project: true,
+  'image-editor': true,
   'profile-feedback': false,
   'work-detail': true,
   detail: true,
diff --git a/src/components/project/ProjectCanvasCover.tsx b/src/components/project/ProjectCanvasCover.tsx
new file mode 100644
index 000000000..e598f3562
--- /dev/null
+++ b/src/components/project/ProjectCanvasCover.tsx
@@ -0,0 +1,159 @@
+import type {
+  EditorProjectLayerSnapshot,
+  EditorProjectResourceSnapshot,
+  EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import { ResolvedAssetImage } from '../ResolvedAssetImage';
+
+export const PROJECT_CANVAS_COVER_SIZE = { width: 320, height: 240 } as const;
+export const PROJECT_CANVAS_COVER_VIEWPORT_SIZE = {
+  width: 900,
+  height: 640,
+} as const;
+
+export type ProjectCanvasCoverLayer = {
+  layerId: string;
+  title: string;
+  imageSrc: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  zIndex: number;
+};
+
+export type ProjectCanvasCoverClassNames = {
+  root?: string;
+  empty?: string;
+  layer?: string;
+  image?: string;
+};
+
+export type ProjectCanvasCoverProps = {
+  project: EditorProjectSnapshot;
+  classNames?: ProjectCanvasCoverClassNames;
+};
+
+function numberFromLayer(
+  layer: EditorProjectLayerSnapshot,
+  key: string,
+  fallback: number,
+) {
+  const value = layer[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function stringFromLayer(layer: EditorProjectLayerSnapshot, key: string) {
+  const value = layer[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function isLayerHidden(layer: EditorProjectLayerSnapshot) {
+  return layer.hidden === true;
+}
+
+function joinClassNames(...classNames: Array<string | undefined>) {
+  return classNames.filter(Boolean).join(' ');
+}
+
+export function resolveProjectCanvasCoverLayers(
+  project: EditorProjectSnapshot,
+): ProjectCanvasCoverLayer[] {
+  const resourcesById = new Map<string, EditorProjectResourceSnapshot>(
+    project.resources.map((resource) => [resource.resourceId, resource]),
+  );
+
+  return project.layers
+    .filter((layer) => !isLayerHidden(layer))
+    .map((layer) => {
+      const resource = resourcesById.get(layer.resourceId);
+      const imageSrc = stringFromLayer(layer, 'src') || resource?.imageSrc.trim() || '';
+      if (!imageSrc) {
+        return null;
+      }
+      return {
+        layerId: layer.layerId,
+        title: stringFromLayer(layer, 'title') || '画布图片',
+        imageSrc,
+        x: numberFromLayer(layer, 'x', 0),
+        y: numberFromLayer(layer, 'y', 0),
+        width: Math.max(1, numberFromLayer(layer, 'width', resource?.width ?? 320)),
+        height: Math.max(1, numberFromLayer(layer, 'height', resource?.height ?? 320)),
+        zIndex: numberFromLayer(layer, 'zIndex', 0),
+      } satisfies ProjectCanvasCoverLayer;
+    })
+    .filter((layer): layer is ProjectCanvasCoverLayer => Boolean(layer))
+    .sort((left, right) => left.zIndex - right.zIndex);
+}
+
+export function ProjectCanvasCover({
+  project,
+  classNames,
+}: ProjectCanvasCoverProps) {
+  const coverLayers = resolveProjectCanvasCoverLayers(project);
+  if (!coverLayers.length) {
+    return (
+      <span
+        className={joinClassNames(
+          'project-gallery__preview-empty',
+          classNames?.empty,
+        )}
+      />
+    );
+  }
+
+  const safeScale =
+    project.viewport.scale > 0 && Number.isFinite(project.viewport.scale)
+      ? project.viewport.scale
+      : 1;
+  const viewportCenterX =
+    (PROJECT_CANVAS_COVER_VIEWPORT_SIZE.width / 2 - project.viewport.x) /
+    safeScale;
+  const viewportCenterY =
+    (PROJECT_CANVAS_COVER_VIEWPORT_SIZE.height / 2 - project.viewport.y) /
+    safeScale;
+  const worldPreviewWidth = PROJECT_CANVAS_COVER_VIEWPORT_SIZE.width / safeScale;
+  const worldPreviewHeight =
+    PROJECT_CANVAS_COVER_VIEWPORT_SIZE.height / safeScale;
+  const previewMinX = viewportCenterX - worldPreviewWidth / 2;
+  const previewMinY = viewportCenterY - worldPreviewHeight / 2;
+  const scale = Math.min(
+    PROJECT_CANVAS_COVER_SIZE.width / worldPreviewWidth,
+    PROJECT_CANVAS_COVER_SIZE.height / worldPreviewHeight,
+  );
+  const offsetX = -previewMinX * scale;
+  const offsetY = -previewMinY * scale;
+
+  return (
+    <span
+      className={joinClassNames('project-gallery__canvas-cover', classNames?.root)}
+      aria-hidden="true"
+    >
+      {coverLayers.map((layer) => (
+        <span
+          key={layer.layerId}
+          className={joinClassNames(
+            'project-gallery__canvas-cover-layer',
+            classNames?.layer,
+          )}
+          style={{
+            left: offsetX + layer.x * scale,
+            top: offsetY + layer.y * scale,
+            width: layer.width * scale,
+            height: layer.height * scale,
+            zIndex: layer.zIndex,
+          }}
+        >
+          <ResolvedAssetImage
+            src={layer.imageSrc}
+            alt=""
+            className={joinClassNames(
+              'project-gallery__canvas-cover-image',
+              classNames?.image,
+            )}
+          />
+        </span>
+      ))}
+    </span>
+  );
+}
diff --git a/src/components/project/ProjectGalleryView.test.tsx b/src/components/project/ProjectGalleryView.test.tsx
new file mode 100644
index 000000000..b1ebc5ff6
--- /dev/null
+++ b/src/components/project/ProjectGalleryView.test.tsx
@@ -0,0 +1,327 @@
+/* @vitest-environment jsdom */
+
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ComponentProps, ContextType } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ApiClientError } from '../../services/apiClient';
+import { AuthUiContext } from '../auth/AuthUiContext';
+import { ProjectGalleryView } from './ProjectGalleryView';
+
+const listEditorProjectsMock = vi.hoisted(() => vi.fn());
+const createEditorProjectMock = vi.hoisted(() => vi.fn());
+const renameEditorProjectMock = vi.hoisted(() => vi.fn());
+const deleteEditorProjectMock = vi.hoisted(() => vi.fn());
+
+type AuthValue = NonNullable<ContextType<typeof AuthUiContext>>;
+
+function createAuthValue(overrides: Partial<AuthValue> = {}): AuthValue {
+  return {
+    user: null,
+    canAccessProtectedData: false,
+    openLoginModal: vi.fn(),
+    requireAuth: vi.fn((action: () => void) => action()),
+    openSettingsModal: vi.fn(),
+    openAccountModal: vi.fn(),
+    setCurrentUser: vi.fn(),
+    logout: vi.fn(),
+    musicVolume: 0.5,
+    setMusicVolume: vi.fn(),
+    platformTheme: 'light' as const,
+    setPlatformTheme: vi.fn(),
+    isHydratingSettings: false,
+    isPersistingSettings: false,
+    settingsError: null,
+    ...overrides,
+  };
+}
+
+vi.mock('../../services/image-editor/editorProjectClient', () => ({
+  listEditorProjects: listEditorProjectsMock,
+  createEditorProject: createEditorProjectMock,
+  renameEditorProject: renameEditorProjectMock,
+  deleteEditorProject: deleteEditorProjectMock,
+}));
+
+const projectItems = [
+  {
+    projectId: 'editor-project-1',
+    title: '角色设定板',
+    viewport: { x: 0, y: 0, scale: 1 },
+    layers: [{ layerId: 'layer-1', resourceId: 'resource-1' }],
+    resources: [
+      {
+        resourceId: 'resource-1',
+        projectId: 'editor-project-1',
+        imageSrc: 'data:image/png;base64,one',
+        width: 1024,
+        height: 1024,
+        sourceType: 'uploaded',
+      },
+    ],
+    updatedAt: '2026-06-12T08:00:00.000Z',
+  },
+  {
+    projectId: 'editor-project-2',
+    title: '场景草图',
+    viewport: { x: 0, y: 0, scale: 1 },
+    layers: [],
+    resources: [],
+    updatedAt: '2026-06-12T07:00:00.000Z',
+  },
+];
+
+function renderProjectGalleryView(
+  props: Partial<ComponentProps<typeof ProjectGalleryView>> = {},
+) {
+  return render(
+    <ProjectGalleryView
+      onOpenProject={vi.fn()}
+      onReturnToMainSite={vi.fn()}
+      {...props}
+    />,
+  );
+}
+
+describe('ProjectGalleryView', () => {
+  afterEach(() => {
+    listEditorProjectsMock.mockReset();
+    createEditorProjectMock.mockReset();
+    renameEditorProjectMock.mockReset();
+    deleteEditorProjectMock.mockReset();
+  });
+
+  it('opens a project from the gallery card', async () => {
+    const onOpenProject = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    const user = userEvent.setup();
+
+    renderProjectGalleryView({ onOpenProject });
+
+    await screen.findByText('角色设定板');
+    await user.click(screen.getByRole('button', { name: '打开项目角色设定板' }));
+
+    expect(onOpenProject).toHaveBeenCalledWith('editor-project-1');
+  });
+
+  it('returns to the main site from the project header', async () => {
+    const onReturnToMainSite = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    const user = userEvent.setup();
+
+    renderProjectGalleryView({ onReturnToMainSite });
+
+    await screen.findByText('角色设定板');
+    await user.click(screen.getByRole('button', { name: '返回主站' }));
+
+    expect(onReturnToMainSite).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses canvas-center layer composition as the project cover', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce([
+      {
+        projectId: 'editor-project-cover',
+        title: '封面项目',
+        viewport: { x: 120, y: -60, scale: 0.8 },
+        layers: [
+          {
+            layerId: 'layer-cover-back',
+            resourceId: 'resource-back',
+            title: '背景图',
+            x: 200,
+            y: 160,
+            width: 300,
+            height: 180,
+            zIndex: 1,
+          },
+          {
+            layerId: 'layer-cover-front',
+            resourceId: 'resource-front',
+            title: '前景图',
+            x: 420,
+            y: 260,
+            width: 160,
+            height: 120,
+            zIndex: 2,
+          },
+        ],
+        resources: [
+          {
+            resourceId: 'resource-front',
+            projectId: 'editor-project-cover',
+            imageSrc: 'data:image/png;base64,front',
+            width: 160,
+            height: 120,
+            sourceType: 'uploaded',
+          },
+          {
+            resourceId: 'resource-back',
+            projectId: 'editor-project-cover',
+            imageSrc: 'data:image/png;base64,back',
+            width: 300,
+            height: 180,
+            sourceType: 'uploaded',
+          },
+        ],
+        updatedAt: '2026-06-12T08:00:00.000Z',
+      },
+    ]);
+
+    renderProjectGalleryView();
+
+    await screen.findByText('封面项目');
+    const cover = document.querySelector('.project-gallery__canvas-cover');
+    const coverLayers = document.querySelectorAll(
+      '.project-gallery__canvas-cover-layer',
+    );
+
+    expect(cover).toBeTruthy();
+    expect(coverLayers).toHaveLength(2);
+    expect(
+      document.querySelector('.project-gallery__preview img')?.getAttribute('src'),
+    ).toBe('data:image/png;base64,back');
+    expect((coverLayers[0] as HTMLElement).style.zIndex).toBe('1');
+    expect((coverLayers[1] as HTMLElement).style.zIndex).toBe('2');
+  });
+
+  it('opens the login modal when project list loading is unauthorized', async () => {
+    const openLoginModal = vi.fn();
+    listEditorProjectsMock.mockRejectedValueOnce(
+      new ApiClientError({
+        message: '未授权访问',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
+    );
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue({ openLoginModal })}>
+        <ProjectGalleryView
+          onOpenProject={vi.fn()}
+          onReturnToMainSite={vi.fn()}
+        />
+      </AuthUiContext.Provider>,
+    );
+
+    await waitFor(() => {
+      expect(openLoginModal).toHaveBeenCalledTimes(1);
+    });
+    expect(openLoginModal).toHaveBeenCalledWith(expect.any(Function));
+    expect(screen.queryByRole('alert')).toBeNull();
+  });
+
+  it('requires login before opening a project card while logged out', async () => {
+    const onOpenProject = vi.fn();
+    const requireAuth = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    const user = userEvent.setup();
+
+    render(
+      <AuthUiContext.Provider value={createAuthValue({ requireAuth })}>
+        <ProjectGalleryView
+          onOpenProject={onOpenProject}
+          onReturnToMainSite={vi.fn()}
+        />
+      </AuthUiContext.Provider>,
+    );
+
+    await screen.findByText('角色设定板');
+    await user.click(screen.getByRole('button', { name: '打开项目角色设定板' }));
+
+    expect(requireAuth).toHaveBeenCalledWith(expect.any(Function));
+    expect(onOpenProject).not.toHaveBeenCalled();
+  });
+
+  it('renders project loading errors through the shared status message', async () => {
+    listEditorProjectsMock.mockRejectedValueOnce(new Error('读取项目失败'));
+
+    renderProjectGalleryView();
+
+    const alert = await screen.findByRole('alert');
+
+    expect(alert.textContent).toContain('读取项目失败');
+    expect(alert.className).toContain('platform-status-message');
+    expect(alert.className).toContain('project-gallery__error');
+  });
+
+  it('renames and deletes a project from the hover menu', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    renameEditorProjectMock.mockResolvedValueOnce({
+      ...projectItems[0],
+      title: '新角色设定板',
+    });
+    deleteEditorProjectMock.mockResolvedValueOnce('editor-project-2');
+    const user = userEvent.setup();
+
+    renderProjectGalleryView();
+
+    await screen.findByText('角色设定板');
+    await user.click(screen.getByRole('button', { name: '打开项目角色设定板菜单' }));
+    await user.click(screen.getByRole('menuitem', { name: /重命名/u }));
+    await user.clear(screen.getByLabelText('项目名称'));
+    await user.type(screen.getByLabelText('项目名称'), '新角色设定板');
+    await user.click(screen.getByRole('button', { name: '保存' }));
+
+    expect(renameEditorProjectMock).toHaveBeenCalledWith(
+      'editor-project-1',
+      '新角色设定板',
+    );
+    await screen.findByText('新角色设定板');
+
+    await user.click(screen.getByRole('button', { name: '打开项目场景草图菜单' }));
+    await user.click(screen.getByRole('menuitem', { name: /删除/u }));
+
+    expect(deleteEditorProjectMock).toHaveBeenCalledWith('editor-project-2');
+    await waitFor(() => {
+      expect(screen.queryByText('场景草图')).toBeNull();
+    });
+  });
+
+  it('supports batch selection actions from the bottom toolbar', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    deleteEditorProjectMock.mockResolvedValue('deleted');
+    const user = userEvent.setup();
+
+    renderProjectGalleryView();
+
+    await screen.findByText('角色设定板');
+    await user.click(screen.getByRole('button', { name: '选择' }));
+    const toolbar = screen.getByRole('toolbar', { name: '批量操作' });
+
+    await user.click(within(toolbar).getByRole('button', { name: '全选' }));
+
+    expect(
+      within(toolbar).getByRole('button', { name: '取消全选 · 已选 2' }),
+    ).toBeTruthy();
+
+    await user.click(within(toolbar).getByRole('button', { name: '删除' }));
+
+    expect(deleteEditorProjectMock).toHaveBeenCalledWith('editor-project-1');
+    expect(deleteEditorProjectMock).toHaveBeenCalledWith('editor-project-2');
+  });
+
+  it('renders the empty project action with shared empty state chrome', async () => {
+    const onOpenProject = vi.fn();
+    listEditorProjectsMock.mockResolvedValueOnce([]);
+    createEditorProjectMock.mockResolvedValueOnce({
+      ...projectItems[0],
+      projectId: 'editor-project-new',
+    });
+    const user = userEvent.setup();
+
+    renderProjectGalleryView({ onOpenProject });
+
+    const newProjectButton = await screen.findByRole('button', {
+      name: '新建项目',
+    });
+
+    expect(newProjectButton.className).toContain('platform-empty-state');
+    expect(newProjectButton.className).toContain('project-gallery__new-card');
+
+    await user.click(newProjectButton);
+
+    expect(createEditorProjectMock).toHaveBeenCalledTimes(1);
+    expect(onOpenProject).toHaveBeenCalledWith('editor-project-new');
+  });
+});
diff --git a/src/components/project/ProjectGalleryView.tsx b/src/components/project/ProjectGalleryView.tsx
new file mode 100644
index 000000000..1a29fdf55
--- /dev/null
+++ b/src/components/project/ProjectGalleryView.tsx
@@ -0,0 +1,449 @@
+import {
+  ArrowLeft,
+  Check,
+  CheckSquare,
+  MoreHorizontal,
+  Pencil,
+  Plus,
+  Square,
+  Trash2,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import {
+  createEditorProject,
+  deleteEditorProject,
+  listEditorProjects,
+  renameEditorProject,
+  type EditorProjectSnapshot,
+} from '../../services/image-editor/editorProjectClient';
+import { ApiClientError } from '../../services/apiClient';
+import { useAuthUi } from '../auth/AuthUiContext';
+import { PlatformActionButton } from '../common/PlatformActionButton';
+import { PlatformBatchActionToolbar } from '../common/PlatformBatchActionToolbar';
+import { PlatformEmptyState } from '../common/PlatformEmptyState';
+import {
+  PlatformFloatingMenu,
+  PlatformFloatingMenuItem,
+} from '../common/PlatformFloatingMenu';
+import { PlatformIconButton } from '../common/PlatformIconButton';
+import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { UnifiedModal } from '../common/UnifiedModal';
+import { ProjectCanvasCover } from './ProjectCanvasCover';
+
+type ProjectGalleryViewProps = {
+  onOpenProject: (projectId: string) => void;
+  onReturnToMainSite: () => void;
+};
+
+type RenameDraft = {
+  projectId: string;
+  title: string;
+};
+
+function isUnauthorizedError(error: unknown) {
+  return error instanceof ApiClientError && error.status === 401;
+}
+
+function formatProjectUpdatedAt(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+  return new Intl.DateTimeFormat('zh-CN', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+}
+
+export function ProjectGalleryView({
+  onOpenProject,
+  onReturnToMainSite,
+}: ProjectGalleryViewProps) {
+  const authUi = useAuthUi();
+  const [projects, setProjects] = useState<EditorProjectSnapshot[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [activeMenuProjectId, setActiveMenuProjectId] = useState<string | null>(
+    null,
+  );
+  const [renameDraft, setRenameDraft] = useState<RenameDraft | null>(null);
+  const [selectedProjectIds, setSelectedProjectIds] = useState<Set<string>>(
+    () => new Set(),
+  );
+  const [isSelectionMode, setIsSelectionMode] = useState(false);
+  const selectedCount = selectedProjectIds.size;
+  const allSelected =
+    projects.length > 0 && selectedProjectIds.size === projects.length;
+
+  const refreshProjects = useCallback(() => {
+    setIsLoading(true);
+    setErrorMessage(null);
+    listEditorProjects()
+      .then((items) => {
+        setProjects(items);
+        setSelectedProjectIds((currentIds) => {
+          const availableIds = new Set(items.map((project) => project.projectId));
+          return new Set(
+            [...currentIds].filter((projectId) => availableIds.has(projectId)),
+          );
+        });
+      })
+      .catch((error: unknown) => {
+        if (isUnauthorizedError(error)) {
+          authUi?.openLoginModal(refreshProjects);
+          return;
+        }
+        setErrorMessage(
+          error instanceof Error ? error.message : '读取项目列表失败',
+        );
+      })
+      .finally(() => setIsLoading(false));
+  }, [authUi]);
+
+  useEffect(() => {
+    refreshProjects();
+  }, [refreshProjects]);
+
+  const createProject = useCallback(() => {
+    if (authUi && !authUi.user) {
+      authUi.openLoginModal(createProject);
+      return;
+    }
+    setErrorMessage(null);
+    createEditorProject()
+      .then((project) => onOpenProject(project.projectId))
+      .catch((error: unknown) => {
+        setErrorMessage(
+          error instanceof Error ? error.message : '创建项目失败',
+        );
+      });
+  }, [authUi, onOpenProject]);
+
+  const closeSelectionMode = useCallback(() => {
+    setIsSelectionMode(false);
+    setSelectedProjectIds(new Set());
+  }, []);
+
+  const toggleProjectSelection = useCallback((projectId: string) => {
+    setSelectedProjectIds((currentIds) => {
+      const nextIds = new Set(currentIds);
+      if (nextIds.has(projectId)) {
+        nextIds.delete(projectId);
+      } else {
+        nextIds.add(projectId);
+      }
+      return nextIds;
+    });
+  }, []);
+
+  const deleteProjects = useCallback(
+    (projectIds: string[]) => {
+      if (projectIds.length === 0) {
+        return;
+      }
+      setErrorMessage(null);
+      void Promise.all(projectIds.map((projectId) => deleteEditorProject(projectId)))
+        .then(() => {
+          setProjects((currentProjects) =>
+            currentProjects.filter(
+              (project) => !projectIds.includes(project.projectId),
+            ),
+          );
+          setSelectedProjectIds((currentIds) => {
+            const nextIds = new Set(currentIds);
+            projectIds.forEach((projectId) => nextIds.delete(projectId));
+            return nextIds;
+          });
+          setActiveMenuProjectId(null);
+        })
+        .catch((error: unknown) => {
+          setErrorMessage(
+            error instanceof Error ? error.message : '删除项目失败',
+          );
+        });
+    },
+    [],
+  );
+
+  const submitRename = useCallback(() => {
+    if (!renameDraft) {
+      return;
+    }
+    const title = renameDraft.title.trim();
+    if (!title) {
+      return;
+    }
+    setErrorMessage(null);
+    renameEditorProject(renameDraft.projectId, title)
+      .then((project) => {
+        setProjects((currentProjects) =>
+          currentProjects.map((item) =>
+            item.projectId === project.projectId ? project : item,
+          ),
+        );
+        setRenameDraft(null);
+        setActiveMenuProjectId(null);
+      })
+      .catch((error: unknown) => {
+        setErrorMessage(
+          error instanceof Error ? error.message : '重命名项目失败',
+        );
+      });
+  }, [renameDraft]);
+
+  const projectCards = useMemo(
+    () =>
+      projects.map((project) => {
+        const selected = selectedProjectIds.has(project.projectId);
+        return (
+          <article
+            key={project.projectId}
+            className={[
+              'project-gallery__card',
+              selected ? 'project-gallery__card--selected' : '',
+            ]
+              .filter(Boolean)
+              .join(' ')}
+          >
+            <button
+              type="button"
+              className="project-gallery__card-button"
+              onClick={() => {
+                if (isSelectionMode) {
+                  toggleProjectSelection(project.projectId);
+                  return;
+                }
+                if (authUi) {
+                  authUi.requireAuth(() => onOpenProject(project.projectId));
+                  return;
+                }
+                onOpenProject(project.projectId);
+              }}
+              aria-label={`打开项目${project.title}`}
+            >
+              <PlatformMediaFrame
+                src={null}
+                alt=""
+                fallbackLabel="项目"
+                aspect="standard"
+                surface="bright"
+                className="project-gallery__preview"
+                fallbackContent={<ProjectCanvasCover project={project} />}
+              >
+                {isSelectionMode ? (
+                  <span className="project-gallery__checkbox">
+                    {selected ? <Check className="h-4 w-4" /> : null}
+                  </span>
+                ) : null}
+              </PlatformMediaFrame>
+              <span className="project-gallery__meta">
+                <span>{project.title}</span>
+                <span>{formatProjectUpdatedAt(project.updatedAt)}</span>
+              </span>
+            </button>
+            {!isSelectionMode ? (
+              <div className="project-gallery__card-menu-wrap">
+                <PlatformIconButton
+                  label={`打开项目${project.title}菜单`}
+                  icon={<MoreHorizontal className="h-4 w-4" />}
+                  variant="surfaceFloating"
+                  className="h-8 w-8"
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    setActiveMenuProjectId((currentProjectId) =>
+                      currentProjectId === project.projectId
+                        ? null
+                        : project.projectId,
+                    );
+                  }}
+                />
+                {activeMenuProjectId === project.projectId ? (
+                  <PlatformFloatingMenu>
+                    <PlatformFloatingMenuItem
+                      icon={<Pencil className="h-4 w-4" />}
+                      onClick={() =>
+                        setRenameDraft({
+                          projectId: project.projectId,
+                          title: project.title,
+                        })
+                      }
+                    >
+                      重命名
+                    </PlatformFloatingMenuItem>
+                    <PlatformFloatingMenuItem
+                      icon={<Trash2 className="h-4 w-4" />}
+                      onClick={() => deleteProjects([project.projectId])}
+                    >
+                      删除
+                    </PlatformFloatingMenuItem>
+                  </PlatformFloatingMenu>
+                ) : null}
+              </div>
+            ) : null}
+          </article>
+        );
+      }),
+    [
+      activeMenuProjectId,
+      authUi,
+      deleteProjects,
+      isSelectionMode,
+      onOpenProject,
+      projects,
+      selectedProjectIds,
+      toggleProjectSelection,
+    ],
+  );
+
+  return (
+    <main className="project-gallery" aria-label="项目">
+      <header className="project-gallery__header">
+        <div className="project-gallery__heading">
+          <h1>项目</h1>
+          <span>{projects.length} 个画布项目</span>
+        </div>
+        <div className="project-gallery__header-actions">
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            onClick={onReturnToMainSite}
+          >
+            <ArrowLeft className="h-4 w-4" />
+            返回主站
+          </PlatformActionButton>
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            onClick={() => setIsSelectionMode(true)}
+            disabled={projects.length === 0}
+          >
+            选择
+          </PlatformActionButton>
+          <PlatformActionButton size="sm" onClick={createProject}>
+            <Plus className="h-4 w-4" />
+            新建
+          </PlatformActionButton>
+        </div>
+      </header>
+
+      {errorMessage ? (
+        <PlatformStatusMessage
+          tone="error"
+          surface="platform"
+          className="project-gallery__error"
+          role="alert"
+        >
+          {errorMessage}
+        </PlatformStatusMessage>
+      ) : null}
+
+      {isLoading ? (
+        <PlatformEmptyState surface="subpanel" size="panel">
+          正在读取项目
+        </PlatformEmptyState>
+      ) : projects.length === 0 ? (
+        <PlatformEmptyState
+          asChild="button"
+          surface="subpanel"
+          size="panel"
+          className="project-gallery__new-card"
+          onClick={createProject}
+        >
+          <Plus className="h-6 w-6" />
+          <span>新建项目</span>
+        </PlatformEmptyState>
+      ) : (
+        <section className="project-gallery__grid">{projectCards}</section>
+      )}
+
+      <UnifiedModal
+        open={Boolean(renameDraft)}
+        title="重命名"
+        size="sm"
+        closeLabel="关闭重命名"
+        onClose={() => setRenameDraft(null)}
+        footer={
+          <>
+            <PlatformActionButton
+              type="button"
+              tone="secondary"
+              onClick={() => setRenameDraft(null)}
+            >
+              取消
+            </PlatformActionButton>
+            <PlatformActionButton type="submit" form="project-gallery-rename-form">
+              保存
+            </PlatformActionButton>
+          </>
+        }
+      >
+        {renameDraft ? (
+          <form
+            id="project-gallery-rename-form"
+            onSubmit={(event) => {
+              event.preventDefault();
+              submitRename();
+            }}
+          >
+            <PlatformTextField
+              aria-label="项目名称"
+              value={renameDraft.title}
+              onChange={(event) =>
+                setRenameDraft((currentDraft) =>
+                  currentDraft
+                    ? { ...currentDraft, title: event.target.value }
+                    : currentDraft,
+                )
+              }
+              autoFocus
+            />
+          </form>
+        ) : null}
+      </UnifiedModal>
+
+      {isSelectionMode ? (
+        <PlatformBatchActionToolbar>
+          <PlatformActionButton
+            tone="secondary"
+            size="sm"
+            onClick={() => {
+              setSelectedProjectIds(
+                allSelected
+                  ? new Set()
+                  : new Set(projects.map((project) => project.projectId)),
+              );
+            }}
+          >
+            {allSelected ? (
+              <CheckSquare className="h-4 w-4" />
+            ) : (
+              <Square className="h-4 w-4" />
+            )}
+            {selectedCount > 0
+              ? `${allSelected ? '取消全选' : '全选'} · 已选 ${selectedCount}`
+              : '全选'}
+          </PlatformActionButton>
+          <PlatformActionButton
+            tone="warning"
+            size="sm"
+            disabled={selectedCount === 0}
+            onClick={() => deleteProjects([...selectedProjectIds])}
+          >
+            <Trash2 className="h-4 w-4" />
+            删除
+          </PlatformActionButton>
+          <PlatformActionButton tone="secondary" size="sm" onClick={closeSelectionMode}>
+            取消
+          </PlatformActionButton>
+        </PlatformBatchActionToolbar>
+      ) : null}
+    </main>
+  );
+}
+
+export default ProjectGalleryView;
diff --git a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
index 226fc2888..d2153e61a 100644
--- a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
+++ b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
@@ -94,6 +94,10 @@ import {
   regenerateBabyObjectMatchDraftAssets,
   saveBabyObjectMatchDraft,
 } from '../../services/edutainment-baby-object';
+import {
+  listEditorProjects,
+  loadEditorAssetLibrary,
+} from '../../services/image-editor/editorProjectClient';
 import { jumpHopClient } from '../../services/jump-hop/jumpHopClient';
 import { match3dCreationClient } from '../../services/match3d-creation';
 import { createServerMatch3DRuntimeAdapter } from '../../services/match3d-runtime';
@@ -185,6 +189,7 @@ import {
   AuthUiContext,
   type PlatformSettingsSection,
 } from '../auth/AuthUiContext';
+import { PLATFORM_DESKTOP_LAYOUT_QUERY } from '../platform-entry/platformEntryResponsive';
 import {
   getUnifiedCreationSpec,
   type UnifiedCreationPlayId,
@@ -702,6 +707,14 @@ vi.mock('../../services/edutainment-baby-object', () => ({
   saveBabyObjectMatchDraft: vi.fn(),
 }));
 
+vi.mock('../../services/image-editor/editorProjectClient', () => ({
+  createEditorProject: vi.fn(),
+  deleteEditorProject: vi.fn(),
+  listEditorProjects: vi.fn(),
+  loadEditorAssetLibrary: vi.fn(async () => ({ assets: [] })),
+  renameEditorProject: vi.fn(),
+}));
+
 vi.mock('../../services/wooden-fish/woodenFishClient', () => ({
   woodenFishClient: {
     checkpointRun: vi.fn(),
@@ -2528,6 +2541,25 @@ function createAuthValue(
   };
 }
 
+const originalMatchMedia = window.matchMedia;
+
+function mockDesktopPlatformLayout() {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+      matches: query === PLATFORM_DESKTOP_LAYOUT_QUERY,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+}
+
 function TestWrapper({
   withAuth = false,
   authValue,
@@ -2697,6 +2729,11 @@ beforeEach(() => {
   });
   vi.mocked(listRpgEntryWorldLibrary).mockResolvedValue([]);
   vi.mocked(listRpgEntryWorldGallery).mockResolvedValue([]);
+  vi.mocked(listEditorProjects).mockResolvedValue([]);
+  vi.mocked(loadEditorAssetLibrary).mockResolvedValue({
+    assets: [],
+    folders: [],
+  });
   vi.mocked(getRpgEntryWorldGalleryDetail).mockImplementation(
     async (ownerUserId, profileId) =>
       buildMockRpgGalleryDetail({
@@ -3779,6 +3816,11 @@ beforeEach(() => {
 
 afterEach(() => {
   vi.unstubAllEnvs();
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    writable: true,
+    value: originalMatchMedia,
+  });
 });
 
 test('create tab shows template tabs and embeds puzzle form by default', async () => {
@@ -9087,18 +9129,161 @@ test('embedded puzzle form maps raw bearer token errors to user-facing auth copy
   expect(screen.queryByText('缺少 Authorization Bearer Token')).toBeNull();
 });
 
-test('create tab does not render legacy gameplay creation entries', async () => {
-  const user = userEvent.setup();
+test('creation home does not render legacy gameplay creation entries', async () => {
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/creation');
+  const { container } = render(<TestWrapper withAuth />);
 
-  render(<TestWrapper withAuth />);
-
-  await openCreateTemplateHub(user);
+  expect(
+    await screen.findByRole('heading', {
+      name: '陶泥儿 - 开启全民精品游戏创作',
+    }),
+  ).toBeTruthy();
 
+  expect(container.querySelector('.platform-desktop-topbar')).toBeTruthy();
+  expect(container.querySelector('.platform-desktop-rail')).toBeTruthy();
   expect(screen.queryByText('选择创作类型')).toBeNull();
   expect(screen.queryByRole('button', { name: /大鱼吃小鱼/u })).toBeNull();
   expect(createBigFishCreationSession).not.toHaveBeenCalled();
 });
 
+test('creation home community opens in place without switching to profile', async () => {
+  const user = userEvent.setup();
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/creation');
+  render(<TestWrapper withAuth />);
+
+  await screen.findByRole('heading', {
+    name: '陶泥儿 - 开启全民精品游戏创作',
+  });
+  await user.click(screen.getByRole('button', { name: '玩家社区' }));
+
+  expect(window.location.pathname).toBe('/creation');
+  expect(window.location.search).toBe('');
+  const dialog = await screen.findByRole('dialog', { name: '玩家社区' });
+  expect(within(dialog).getByAltText('玩家社区微信群二维码')).toBeTruthy();
+  expect(within(dialog).getByAltText('玩家社区 QQ 群二维码')).toBeTruthy();
+  expect(screen.queryByText('陶泥号')).toBeNull();
+});
+
+test('creation home desktop rail can return to platform tabs', async () => {
+  const user = userEvent.setup();
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/creation');
+  const { container } = render(<TestWrapper withAuth />);
+
+  await screen.findByRole('heading', {
+    name: '陶泥儿 - 开启全民精品游戏创作',
+  });
+  const nav = container.querySelector('.platform-desktop-rail');
+  expect(nav).toBeTruthy();
+
+  await user.click(within(nav as HTMLElement).getByRole('button', { name: '推荐' }));
+
+  await waitFor(() => {
+    expect(screen.queryByRole('main', { name: '陶泥儿创作主页' })).toBeNull();
+  });
+  expect(window.location.pathname).toBe('/');
+});
+
+test('project page keeps desktop rail and can return to platform tabs', async () => {
+  const user = userEvent.setup();
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/project');
+  const { container } = render(<TestWrapper withAuth />);
+
+  expect(await screen.findByRole('main', { name: '项目' })).toBeTruthy();
+  const nav = container.querySelector('.platform-desktop-rail');
+  expect(nav).toBeTruthy();
+  const createNavButton = within(nav as HTMLElement).getByRole('button', {
+    name: '创作',
+  });
+  const projectNavButton = within(nav as HTMLElement).getByRole('button', {
+    name: '项目',
+  });
+  expect(projectNavButton.className).toContain(
+    'platform-desktop-rail__button--active',
+  );
+  expect(createNavButton.className).not.toContain(
+    'platform-desktop-rail__button--active',
+  );
+  expect(createNavButton.className).not.toContain(
+    'platform-desktop-rail__button--primary',
+  );
+
+  await user.click(within(nav as HTMLElement).getByRole('button', { name: '推荐' }));
+
+  await waitFor(() => {
+    expect(screen.queryByRole('main', { name: '项目' })).toBeNull();
+  });
+  expect(window.location.pathname).toBe('/');
+});
+
+test('desktop project tab switch clears creation primary styling', async () => {
+  const user = userEvent.setup();
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/creation');
+  const { container } = render(<TestWrapper withAuth />);
+
+  await screen.findByRole('main', { name: '陶泥儿创作主页' });
+  const nav = container.querySelector('.platform-desktop-rail');
+  expect(nav).toBeTruthy();
+
+  await user.click(within(nav as HTMLElement).getByRole('button', { name: '项目' }));
+
+  expect(await screen.findByRole('main', { name: '项目' })).toBeTruthy();
+  const projectNav = container.querySelector('.platform-desktop-rail');
+  expect(projectNav).toBeTruthy();
+  const createNavButton = within(projectNav as HTMLElement).getByRole('button', {
+    name: '创作',
+  });
+  const projectNavButton = within(projectNav as HTMLElement).getByRole('button', {
+    name: '项目',
+  });
+  expect(projectNavButton.className).toContain(
+    'platform-desktop-rail__button--active',
+  );
+  expect(createNavButton.className).not.toContain(
+    'platform-desktop-rail__button--active',
+  );
+  expect(createNavButton.className).not.toContain(
+    'platform-desktop-rail__button--primary',
+  );
+});
+
+test('project page header can return to main site', async () => {
+  const user = userEvent.setup();
+  mockDesktopPlatformLayout();
+  window.history.replaceState(null, '', '/project');
+  render(<TestWrapper withAuth />);
+
+  expect(await screen.findByRole('main', { name: '项目' })).toBeTruthy();
+
+  await user.click(screen.getByRole('button', { name: '返回主站' }));
+
+  await waitFor(() => {
+    expect(screen.queryByRole('main', { name: '项目' })).toBeNull();
+  });
+  expect(window.location.pathname).toBe('/');
+});
+
+test('direct mobile creation home keeps landing content without mobile nav entry', async () => {
+  window.history.replaceState(null, '', '/creation');
+  const { container } = render(<TestWrapper withAuth />);
+
+  expect(
+    await screen.findByRole('main', { name: '陶泥儿创作主页' }),
+  ).toBeTruthy();
+  const bottomNav = container.querySelector('.platform-bottom-nav');
+  expect(bottomNav).toBeTruthy();
+  expect(
+    within(bottomNav as HTMLElement).queryByRole('button', { name: '创作' }),
+  ).toBeNull();
+  expect(
+    within(bottomNav as HTMLElement).queryByRole('button', { name: '项目' }),
+  ).toBeNull();
+});
+
 test('embedded puzzle form timeout exits busy state and shows a readable error', async () => {
   const user = userEvent.setup();
 
diff --git a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
index 587d77333..e3401d22c 100644
--- a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
@@ -52,6 +52,9 @@ const {
   mockGetRpgProfileRechargeCenter,
   mockGetRpgProfileTasks,
   mockGetRpgProfileWalletLedger,
+  mockListRpgProfileExternalApiKeys,
+  mockCreateRpgProfileExternalApiKey,
+  mockRevokeRpgProfileExternalApiKey,
   mockRedeemRpgProfileReferralInviteCode,
   mockWatchWechatRpgProfileRechargeOrder,
 } = vi.hoisted(() => {
@@ -327,6 +330,46 @@ const {
         },
       ],
     })),
+    mockListRpgProfileExternalApiKeys: vi.fn(async () => ({
+      keys: [
+        {
+          keyId: 'api-key-1',
+          name: '默认 Key',
+          keyPrefix: 'tnr_sk_existing_1',
+          scopes: ['editor:project', 'editor:canvas', 'editor:image-generate'],
+          createdAt: '2026-06-19T08:00:00Z',
+          lastUsedAt: null,
+          revokedAt: null,
+          updatedAt: '2026-06-19T08:00:00Z',
+        },
+      ],
+    })),
+    mockCreateRpgProfileExternalApiKey: vi.fn(async () => ({
+      apiKey: 'tnr_sk_created.secret',
+      key: {
+        keyId: 'api-key-created',
+        name: '测试 Key',
+        keyPrefix: 'tnr_sk_created',
+        scopes: ['editor:project', 'editor:canvas', 'editor:image-generate'],
+        createdAt: '2026-06-19T09:00:00Z',
+        lastUsedAt: null,
+        revokedAt: null,
+        updatedAt: '2026-06-19T09:00:00Z',
+      },
+    })),
+    mockRevokeRpgProfileExternalApiKey: vi.fn(async (keyId: string) => ({
+      key: {
+        keyId,
+        name: keyId === 'api-key-created' ? '测试 Key' : '默认 Key',
+        keyPrefix:
+          keyId === 'api-key-created' ? 'tnr_sk_created' : 'tnr_sk_existing_1',
+        scopes: ['editor:project', 'editor:canvas', 'editor:image-generate'],
+        createdAt: '2026-06-19T08:00:00Z',
+        lastUsedAt: null,
+        revokedAt: '2026-06-19T10:00:00Z',
+        updatedAt: '2026-06-19T10:00:00Z',
+      },
+    })),
     mockWatchWechatRpgProfileRechargeOrder: vi.fn(async () => null),
   };
 });
@@ -406,6 +449,9 @@ vi.mock('../../services/rpg-entry/rpgProfileClient', () => ({
   getRpgProfileWalletLedger: mockGetRpgProfileWalletLedger,
   claimRpgProfileTaskReward: mockClaimRpgProfileTaskReward,
   redeemRpgProfileReferralInviteCode: mockRedeemRpgProfileReferralInviteCode,
+  listRpgProfileExternalApiKeys: mockListRpgProfileExternalApiKeys,
+  createRpgProfileExternalApiKey: mockCreateRpgProfileExternalApiKey,
+  revokeRpgProfileExternalApiKey: mockRevokeRpgProfileExternalApiKey,
   getRpgProfileRechargeCenter: mockGetRpgProfileRechargeCenter,
   createRpgProfileRechargeOrder: mockCreateRpgProfileRechargeOrder,
   confirmWechatRpgProfileRechargeOrder:
@@ -782,6 +828,8 @@ function ProfileHomeViewHarness({
   profileGenerationQueueStatus = null,
   profilePlayStats = null,
   isProfilePlayStatsOpen = false,
+  initialProfilePopupPanel = null,
+  onInitialProfilePopupPanelConsumed,
 }: {
   onRechargeSuccess?: () => void | Promise<void>;
   profileDashboardOverrides?: Partial<
@@ -793,6 +841,8 @@ function ProfileHomeViewHarness({
   profileGenerationQueueStatus?: RpgEntryHomeViewProps['profileGenerationQueueStatus'];
   profilePlayStats?: ProfilePlayStatsResponse | null;
   isProfilePlayStatsOpen?: boolean;
+  initialProfilePopupPanel?: RpgEntryHomeViewProps['initialProfilePopupPanel'];
+  onInitialProfilePopupPanelConsumed?: RpgEntryHomeViewProps['onInitialProfilePopupPanelConsumed'];
 }) {
   return (
     <AuthUiContext.Provider
@@ -859,6 +909,8 @@ function ProfileHomeViewHarness({
         onRechargeSuccess={onRechargeSuccess}
         profileTaskRefreshKey={profileTaskRefreshKey}
         profileGenerationQueueStatus={profileGenerationQueueStatus}
+        initialProfilePopupPanel={initialProfilePopupPanel}
+        onInitialProfilePopupPanelConsumed={onInitialProfilePopupPanelConsumed}
       />
     </AuthUiContext.Provider>
   );
@@ -875,6 +927,8 @@ function renderProfileView(
     profilePlayStats?: ProfilePlayStatsResponse | null;
     isProfilePlayStatsOpen?: boolean;
     profileGenerationQueueStatus?: RpgEntryHomeViewProps['profileGenerationQueueStatus'];
+    initialProfilePopupPanel?: RpgEntryHomeViewProps['initialProfilePopupPanel'];
+    onInitialProfilePopupPanelConsumed?: RpgEntryHomeViewProps['onInitialProfilePopupPanelConsumed'];
   } = {},
 ) {
   return render(
@@ -888,6 +942,10 @@ function renderProfileView(
       }
       profilePlayStats={profileStatsOptions.profilePlayStats}
       isProfilePlayStatsOpen={profileStatsOptions.isProfilePlayStatsOpen}
+      initialProfilePopupPanel={profileStatsOptions.initialProfilePopupPanel}
+      onInitialProfilePopupPanelConsumed={
+        profileStatsOptions.onInitialProfilePopupPanelConsumed
+      }
     />,
   );
 }
@@ -998,6 +1056,9 @@ function renderLoggedInHomeView(
       | 'draftTabContent'
       | 'myEntries'
       | 'isLoadingPlatform'
+      | 'isDesktopLayout'
+      | 'onOpenCreateTypePicker'
+      | 'onOpenProjects'
     >
   > = {},
 ) {
@@ -1032,6 +1093,7 @@ function renderLoggedInHomeView(
     >
       <RpgEntryHomeView
         activeTab={overrides.activeTab ?? 'saves'}
+        isDesktopLayout={overrides.isDesktopLayout}
         onTabChange={vi.fn()}
         hasSavedGame={false}
         savedSnapshot={null}
@@ -1050,10 +1112,11 @@ function renderLoggedInHomeView(
         onContinueGame={vi.fn()}
         onResumeSave={vi.fn()}
         onOpenCreateWorld={vi.fn()}
-        onOpenCreateTypePicker={vi.fn()}
+        onOpenCreateTypePicker={overrides.onOpenCreateTypePicker ?? vi.fn()}
         onOpenGalleryDetail={vi.fn()}
         onOpenLibraryDetail={vi.fn()}
         onSearchPublicCode={vi.fn()}
+        onOpenProjects={overrides.onOpenProjects}
         hasUnreadDraftUpdate={overrides.hasUnreadDraftUpdate ?? false}
         draftTabContent={overrides.draftTabContent}
       />
@@ -2296,10 +2359,11 @@ test('profile recharge modal blocks tab navigation while virtual payment confirm
   });
 
   expect(screen.getByRole('dialog', { name: '正在确认支付' })).toBeTruthy();
-  expect(
-    (screen.getByRole('button', { name: '创作' }) as HTMLButtonElement)
-      .disabled,
-  ).toBe(true);
+  const nav = document.querySelector('.platform-bottom-nav');
+  expect(nav).toBeTruthy();
+  for (const navButton of within(nav as HTMLElement).getAllByRole('button')) {
+    expect((navButton as HTMLButtonElement).disabled).toBe(true);
+  }
 });
 
 test('profile recharge modal loads wechat js sdk before mini program payment bridge', async () => {
@@ -3064,6 +3128,10 @@ test('mobile profile page matches the reference layout sections', async () => {
       }),
     ).toBeTruthy();
   }
+  expect(
+    within(shortcutRegion).queryByRole('button', { name: /项目/u }),
+  ).toBeNull();
+  expect(shortcutRegion.textContent).not.toContain('画布项目');
   expect(
     within(
       within(shortcutRegion).getByRole('button', { name: /反馈与建议/u }),
@@ -3090,7 +3158,10 @@ test('mobile profile page matches the reference layout sections', async () => {
   ).toBeNull();
   expect(
     settingsRegion.querySelectorAll('.platform-profile-settings-row'),
-  ).toHaveLength(1);
+  ).toHaveLength(2);
+  expect(
+    within(settingsRegion).getByRole('button', { name: /开发者 API Key/u }),
+  ).toBeTruthy();
   expect(
     within(settingsRegion).queryByRole('button', { name: /存档/u }),
   ).toBeNull();
@@ -3324,6 +3395,61 @@ test('profile community shortcut shows reward subtitle and invited users', async
   });
 });
 
+test('profile community popup can be opened from external creation entry', async () => {
+  const onConsumed = vi.fn();
+
+  renderProfileView(
+    vi.fn(),
+    {},
+    {},
+    0,
+    {
+      initialProfilePopupPanel: 'community',
+      onInitialProfilePopupPanelConsumed: onConsumed,
+    },
+  );
+
+  const communityDialog = await screen.findByRole('dialog', {
+    name: '玩家社区',
+  });
+
+  expect(onConsumed).toHaveBeenCalledTimes(1);
+  expect(
+    within(communityDialog).getByRole('button', { name: '关闭玩家社区' }),
+  ).toBeTruthy();
+  expect(screen.getByAltText('玩家社区微信群二维码')).toBeTruthy();
+  expect(screen.getByAltText('玩家社区 QQ 群二维码')).toBeTruthy();
+});
+
+test('profile community popup external open intent can be reused after consume', async () => {
+  const onConsumed = vi.fn();
+  const { rerender } = render(
+    <ProfileHomeViewHarness
+      initialProfilePopupPanel="community"
+      onInitialProfilePopupPanelConsumed={onConsumed}
+    />,
+  );
+
+  expect(await screen.findByRole('dialog', { name: '玩家社区' })).toBeTruthy();
+  expect(onConsumed).toHaveBeenCalledTimes(1);
+
+  rerender(
+    <ProfileHomeViewHarness
+      initialProfilePopupPanel={null}
+      onInitialProfilePopupPanelConsumed={onConsumed}
+    />,
+  );
+  rerender(
+    <ProfileHomeViewHarness
+      initialProfilePopupPanel="community"
+      onInitialProfilePopupPanelConsumed={onConsumed}
+    />,
+  );
+
+  expect(await screen.findByRole('dialog', { name: '玩家社区' })).toBeTruthy();
+  expect(onConsumed).toHaveBeenCalledTimes(2);
+});
+
 test('profile page hides legacy redeem invite secondary shortcut for fresh accounts', async () => {
   renderProfileView(vi.fn(), {});
 
@@ -3483,6 +3609,10 @@ test('profile page shows legal entries and hides archive shortcuts', async () =>
   expect(
     within(shortcutRegion).getByRole('button', { name: /反馈/u }),
   ).toBeTruthy();
+  expect(
+    within(shortcutRegion).queryByRole('button', { name: /项目/u }),
+  ).toBeNull();
+  expect(shortcutRegion.textContent).not.toContain('画布项目');
   const dailyTask = screen.getByRole('button', { name: /每日任务/u });
   expect(dailyTask).toBeTruthy();
   expect(dailyTask.textContent).toContain('完成任务可领取 10 泥点');
@@ -3494,6 +3624,9 @@ test('profile page shows legal entries and hides archive shortcuts', async () =>
   expect(
     within(settingsRegion).getByRole('button', { name: /通用设置/u }),
   ).toBeTruthy();
+  expect(
+    within(settingsRegion).getByRole('button', { name: /开发者 API Key/u }),
+  ).toBeTruthy();
   expect(
     within(settingsRegion).queryByRole('button', { name: /主题设置/u }),
   ).toBeNull();
@@ -3529,6 +3662,48 @@ test('profile page shows legal entries and hides archive shortcuts', async () =>
   expect(await screen.findByRole('dialog', { name: '隐私政策' })).toBeTruthy();
 });
 
+test('profile developer api key entry opens management modal and supports create and revoke', async () => {
+  const user = userEvent.setup();
+
+  renderProfileView();
+
+  await user.click(screen.getByRole('button', { name: /开发者 API Key/u }));
+
+  const dialog = await screen.findByRole('dialog', {
+    name: '开发者 API Key',
+  });
+
+  expect(mockListRpgProfileExternalApiKeys).toHaveBeenCalledTimes(1);
+  expect(within(dialog).getByText('默认 Key')).toBeTruthy();
+  expect(within(dialog).getByText('tnr_sk_existing_1...')).toBeTruthy();
+  expect(within(dialog).queryByText('tnr_sk_created.secret')).toBeNull();
+
+  const nameInput = within(dialog).getByLabelText('名称');
+  await user.clear(nameInput);
+  await user.type(nameInput, '测试 Key');
+  await user.click(within(dialog).getByRole('button', { name: /创建/u }));
+
+  await waitFor(() => {
+    expect(mockCreateRpgProfileExternalApiKey).toHaveBeenCalledWith('测试 Key');
+  });
+  expect(await within(dialog).findByText('tnr_sk_created.secret')).toBeTruthy();
+  expect(within(dialog).getByText('测试 Key')).toBeTruthy();
+
+  const revokeButtons = within(dialog).getAllByRole('button', {
+    name: /撤销/u,
+  });
+  expect(revokeButtons.length).toBeGreaterThan(0);
+  const revokeButton = revokeButtons[0];
+  if (!revokeButton) {
+    throw new Error('撤销按钮不存在');
+  }
+  await user.click(revokeButton);
+  await waitFor(() => {
+    expect(mockRevokeRpgProfileExternalApiKey).toHaveBeenCalled();
+  });
+  expect(within(dialog).getByText('已撤销')).toBeTruthy();
+});
+
 test('shows a reachable login entry outside mobile recommend tab', async () => {
   const user = userEvent.setup();
   const openLoginModal = vi.fn();
@@ -3549,21 +3724,24 @@ test('logged out bottom nav turns active recommend tab into next action', () =>
 
   expect(buttons.map((button) => button.textContent)).toEqual([
     '下一个',
-    '创作',
     '发现',
+    '我的',
   ]);
   expect(buttons[0]?.querySelector('.lucide-chevron-down')).toBeTruthy();
-  expect(buttons[1]?.querySelector('.lucide-sparkles')).toBeTruthy();
-  expect(buttons[2]?.querySelector('.lucide-compass')).toBeTruthy();
+  expect(buttons[1]?.querySelector('.lucide-compass')).toBeTruthy();
+  expect(buttons[2]?.querySelector('.lucide-user-round')).toBeTruthy();
   expect(
-    buttons[1]?.querySelector('.platform-bottom-nav__primary-action'),
-  ).toBeTruthy();
+    within(nav as HTMLElement).queryByRole('button', { name: '创作' }),
+  ).toBeNull();
+  expect(
+    within(nav as HTMLElement).queryByRole('button', { name: '项目' }),
+  ).toBeNull();
   expect(
     buttons[0]?.querySelector('.platform-bottom-nav__active-mark'),
   ).toBeTruthy();
 });
 
-test('logged in draft bottom tab shows unread marker', () => {
+test('logged in mobile bottom nav hides draft and project entries', () => {
   const { container } = renderLoggedInHomeView({
     hasUnreadDraftUpdate: true,
     draftTabContent: <div>草稿内容</div>,
@@ -3571,11 +3749,100 @@ test('logged in draft bottom tab shows unread marker', () => {
 
   const nav = container.querySelector('.platform-bottom-nav');
   expect(nav).toBeTruthy();
-  const draftButton = within(nav as HTMLElement).getByRole('button', {
-    name: '草稿，有新草稿',
+  expect(
+    within(nav as HTMLElement).getByRole('button', { name: '推荐' }),
+  ).toBeTruthy();
+  expect(
+    within(nav as HTMLElement).getByRole('button', { name: '发现' }),
+  ).toBeTruthy();
+  expect(
+    within(nav as HTMLElement).getByRole('button', { name: '我的' }),
+  ).toBeTruthy();
+
+  expect(
+    within(nav as HTMLElement).queryByRole('button', {
+      name: '草稿，有新草稿',
+    }),
+  ).toBeNull();
+  expect(
+    within(nav as HTMLElement).queryByRole('button', { name: '创作' }),
+  ).toBeNull();
+  expect(
+    within(nav as HTMLElement).queryByRole('button', { name: '项目' }),
+  ).toBeNull();
+  expect(nav?.querySelector('.platform-nav-unread-dot')).toBeNull();
+});
+
+test('desktop nav shows creation and projects without draft entry', async () => {
+  const { container } = renderLoggedInHomeView({
+    activeTab: 'profile',
+    isDesktopLayout: true,
+    hasUnreadDraftUpdate: true,
   });
 
-  expect(draftButton.querySelector('.platform-nav-unread-dot')).toBeTruthy();
+  const nav = container.querySelector('.platform-desktop-rail');
+  expect(nav).toBeTruthy();
+  expect(
+    within(nav as HTMLElement).getByRole('button', { name: '创作' }),
+  ).toBeTruthy();
+  expect(
+    within(nav as HTMLElement).getByRole('button', { name: '项目' }),
+  ).toBeTruthy();
+  expect(
+    within(nav as HTMLElement).queryByRole('button', {
+      name: '草稿，有新草稿',
+    }),
+  ).toBeNull();
+  expect(
+    within(nav as HTMLElement).queryByRole('button', { name: /^草稿$/u }),
+  ).toBeNull();
+  await screen.findByText('1 / 1');
+});
+
+test('desktop nav opens creation home and project gallery from dedicated entries', async () => {
+  const user = userEvent.setup();
+  const onOpenCreateTypePicker = vi.fn();
+  const onOpenProjects = vi.fn();
+  const { container } = renderLoggedInHomeView({
+    activeTab: 'profile',
+    isDesktopLayout: true,
+    onOpenCreateTypePicker,
+    onOpenProjects,
+  });
+
+  const nav = container.querySelector('.platform-desktop-rail');
+  expect(nav).toBeTruthy();
+  await user.click(within(nav as HTMLElement).getByRole('button', { name: '创作' }));
+  await user.click(within(nav as HTMLElement).getByRole('button', { name: '项目' }));
+
+  expect(onOpenCreateTypePicker).toHaveBeenCalledTimes(1);
+  expect(onOpenProjects).toHaveBeenCalledTimes(1);
+});
+
+test('desktop recommend page reuses compact workbench chrome', () => {
+  const { container } = renderLoggedInHomeView({
+    activeTab: 'home',
+    isDesktopLayout: true,
+  });
+
+  const shell = container.querySelector('.platform-desktop-shell');
+  expect(shell).toBeTruthy();
+  expect(shell?.className).toContain('platform-desktop-shell--workbench');
+
+  const leftbar = container.querySelector('.platform-desktop-leftbar');
+  const topbar = container.querySelector('.platform-desktop-topbar');
+  expect(leftbar).toBeTruthy();
+  expect(topbar).toBeTruthy();
+  expect(leftbar?.querySelector('.creation-home-brand-lockup')).toBeTruthy();
+  expect(topbar?.querySelector('.creation-home-brand-lockup')).toBeNull();
+  expect(
+    within(leftbar as HTMLElement).getByRole('button', { name: '推荐' }),
+  ).toBeTruthy();
+  expect(
+    within(topbar as HTMLElement).getByPlaceholderText(
+      '搜索作品号、名称、作者、描述',
+    ),
+  ).toBeTruthy();
 });
 
 test('logged in saves tab shows loading state while fetching my entries', () => {
diff --git a/src/components/rpg-entry/RpgEntryHomeView.tsx b/src/components/rpg-entry/RpgEntryHomeView.tsx
index ef7544447..005197429 100644
--- a/src/components/rpg-entry/RpgEntryHomeView.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.tsx
@@ -8,9 +8,11 @@ import {
   Coins,
   Compass,
   Crown,
+  FolderKanban,
   Gamepad2,
   GitFork,
   Heart,
+  KeyRound,
   LogIn,
   MessageCircle,
   Palette,
@@ -126,6 +128,7 @@ import {
 } from '../platform-entry/PlatformProfilePrimitives';
 import { PlatformProfileModalShell } from '../platform-entry/PlatformProfileModalShell';
 import { PlatformProfileGenerationQueueCard } from '../platform-entry/PlatformProfileGenerationQueueCard';
+import { PlatformProfileApiKeysModal } from '../platform-entry/PlatformProfileApiKeysModal';
 import { PlatformProfilePlayedWorksModal } from '../platform-entry/PlatformProfilePlayedWorksModal';
 import { PlatformProfileQrScannerModal } from '../platform-entry/PlatformProfileQrScannerModal';
 import { PlatformProfileRechargeModal } from '../platform-entry/PlatformProfileRechargeModal';
@@ -136,6 +139,7 @@ import { PlatformProfileWalletLedgerModal } from '../platform-entry/PlatformProf
 import type { ExternalGenerationQueueStatus } from '../platform-entry/platformExternalGenerationQueueStatusModel';
 import { getInitialPlatformDesktopLayout } from '../platform-entry/platformEntryResponsive';
 import {
+  type ProfilePopupPanel,
   type RechargePaymentResult,
   usePlatformProfileCenterController,
 } from '../platform-entry/usePlatformProfileCenterController';
@@ -221,8 +225,10 @@ export type PlatformHomeTab =
   | 'create'
   | 'saves'
   | 'profile';
+type PlatformNavTab = PlatformHomeTab | 'projects';
 export interface RpgEntryHomeViewProps {
   activeTab: PlatformHomeTab;
+  activeDesktopNavTab?: PlatformNavTab;
   isDesktopLayout?: boolean;
   onTabChange: (tab: PlatformHomeTab) => void;
   hasSavedGame: boolean;
@@ -274,12 +280,16 @@ export interface RpgEntryHomeViewProps {
   onCloseProfilePlayStats?: () => void;
   onOpenPlayedWork?: (work: ProfilePlayedWorkSummary) => void;
   onOpenFeedback?: () => void;
+  onOpenProjects?: () => void;
   onRechargeSuccess?: () => void | Promise<void>;
   profileTaskRefreshKey?: number;
   profileGenerationQueueStatus?: ExternalGenerationQueueStatus | null;
+  initialProfilePopupPanel?: ProfilePopupPanel | null;
+  onInitialProfilePopupPanelConsumed?: () => void;
   createTabContent?: ReactNode;
   draftTabContent?: ReactNode;
   hasUnreadDraftUpdate?: boolean;
+  allowHiddenActiveTab?: boolean;
 }
 
 const PANEL_SURFACE_CLASS = 'platform-surface platform-surface--soft';
@@ -304,6 +314,26 @@ const PLATFORM_HOME_TABS: PlatformHomeTab[] = [
   'saves',
   'profile',
 ];
+const PLATFORM_DESKTOP_NAV_TABS: PlatformNavTab[] = [
+  'home',
+  'category',
+  'create',
+  'projects',
+  'profile',
+];
+const CREATION_HOME_NAV_ICON_SRC: Record<PlatformNavTab, string> = {
+  home: '/creation-home/nav-recommend.png',
+  category: '/creation-home/nav-discover.png',
+  create: '/creation-home/nav-create.png',
+  projects: '/creation-home/nav-projects.png',
+  saves: '/creation-home/nav-projects.png',
+  profile: '/creation-home/nav-profile.png',
+};
+const CREATION_HOME_TOPBAR_ASSETS = {
+  brandMascot: '/creation-home/brand-mascot.png',
+  search: '/creation-home/topbar-search.png',
+  wallet: '/creation-home/topbar-wallet.png',
+} as const;
 const AVATAR_MAX_FILE_SIZE = 5 * 1024 * 1024;
 const AVATAR_OUTPUT_SIZE = 256;
 const AVATAR_ALLOWED_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);
@@ -996,6 +1026,13 @@ function PublicCodeSearchBar({
     <div
       className={`platform-desktop-search flex min-w-0 items-center gap-3 px-4 py-3 text-[var(--platform-text-soft)] ${className ?? ''}`}
     >
+      <img
+        src={CREATION_HOME_TOPBAR_ASSETS.search}
+        alt=""
+        aria-hidden="true"
+        draggable={false}
+        className="creation-home-topbar-art creation-home-topbar-art--search"
+      />
       <Search className="h-4 w-4 shrink-0" />
       <input
         value={value}
@@ -1050,6 +1087,13 @@ function TopbarWalletShortcutButton({
         .filter(Boolean)
         .join(' ')}
     >
+      <img
+        src={CREATION_HOME_TOPBAR_ASSETS.wallet}
+        alt=""
+        aria-hidden="true"
+        draggable={false}
+        className="creation-home-topbar-art creation-home-topbar-art--wallet"
+      />
       <PlatformIconBadge
         icon={<Coins className="h-3.5 w-3.5" />}
         size="xs"
@@ -1853,6 +1897,7 @@ function DesktopTabButton({
   emphasized = false,
   showDot = false,
   disabled = false,
+  creationHomeIconSrc,
 }: {
   active: boolean;
   label: string;
@@ -1861,6 +1906,7 @@ function DesktopTabButton({
   emphasized?: boolean;
   showDot?: boolean;
   disabled?: boolean;
+  creationHomeIconSrc?: string;
 }) {
   const ariaLabel = showDot ? `${label}，有新草稿` : label;
 
@@ -1873,6 +1919,15 @@ function DesktopTabButton({
       className={`platform-desktop-rail__button ${emphasized ? 'platform-desktop-rail__button--primary' : ''} ${active ? 'platform-desktop-rail__button--active' : ''} disabled:cursor-not-allowed disabled:opacity-55`}
     >
       <span className="platform-desktop-rail__icon-shell">
+        {creationHomeIconSrc ? (
+          <img
+            src={creationHomeIconSrc}
+            alt=""
+            aria-hidden="true"
+            draggable={false}
+            className="creation-home-nav-art"
+          />
+        ) : null}
         <Icon className="platform-desktop-rail__icon h-[1.1rem] w-[1.1rem]" />
         {showDot ? (
           <span aria-hidden="true" className="platform-nav-unread-dot" />
@@ -2526,6 +2581,7 @@ function RechargePaymentConfirmationMask({ orderId }: { orderId: string }) {
 
 export function RpgEntryHomeView({
   activeTab,
+  activeDesktopNavTab,
   isDesktopLayout: isDesktopLayoutProp,
   onTabChange,
   saveEntries,
@@ -2569,12 +2625,16 @@ export function RpgEntryHomeView({
   onCloseProfilePlayStats,
   onOpenPlayedWork,
   onOpenFeedback,
+  onOpenProjects,
   onRechargeSuccess,
   profileTaskRefreshKey = 0,
   profileGenerationQueueStatus = null,
+  initialProfilePopupPanel = null,
+  onInitialProfilePopupPanelConsumed,
   createTabContent,
   draftTabContent,
   hasUnreadDraftUpdate = false,
+  allowHiddenActiveTab = false,
 }: RpgEntryHomeViewProps) {
   const authUi = useAuthUi();
   const showRechargeEntry = shouldShowRechargeEntry();
@@ -2631,6 +2691,7 @@ export function RpgEntryHomeView({
   });
   const [avatarError, setAvatarError] = useState<string | null>(null);
   const [isSavingAvatar, setIsSavingAvatar] = useState(false);
+  const [isApiKeysModalOpen, setIsApiKeysModalOpen] = useState(false);
   const currentUser = authUi?.user ?? null;
   const isAuthenticated = Boolean(currentUser);
   const {
@@ -2698,6 +2759,30 @@ export function RpgEntryHomeView({
     requestLogin: () => authUi?.openLoginModal(),
     currentUser,
   });
+
+  const openedInitialProfilePopupPanelRef = useRef<ProfilePopupPanel | null>(
+    null,
+  );
+  useEffect(() => {
+    if (!initialProfilePopupPanel) {
+      openedInitialProfilePopupPanelRef.current = null;
+      return;
+    }
+    if (
+      activeTab !== 'profile' ||
+      openedInitialProfilePopupPanelRef.current === initialProfilePopupPanel
+    ) {
+      return;
+    }
+    openedInitialProfilePopupPanelRef.current = initialProfilePopupPanel;
+    openProfilePopupPanel(initialProfilePopupPanel);
+    onInitialProfilePopupPanelConsumed?.();
+  }, [
+    activeTab,
+    initialProfilePopupPanel,
+    onInitialProfilePopupPanelConsumed,
+    openProfilePopupPanel,
+  ]);
   const edutainmentEntryEnabled = isEdutainmentEntryEnabled();
   const [fallbackDesktopLayout] = useState(getInitialPlatformDesktopLayout);
   const isDesktopLayout = isDesktopLayoutProp ?? fallbackDesktopLayout;
@@ -2831,11 +2916,18 @@ export function RpgEntryHomeView({
     hasManualCategoryTagSelectionRef.current = true;
     setSelectedCategoryTag(tag);
   }, []);
-  const visibleTabs = useMemo<PlatformHomeTab[]>(
+  const visibleMobileTabs = useMemo<PlatformHomeTab[]>(
     () =>
       isAuthenticated
-        ? ['home', 'category', 'create', 'saves', 'profile']
-        : ['home', 'create', 'category'],
+        ? ['home', 'category', 'profile']
+        : ['home', 'category', 'profile'],
+    [isAuthenticated],
+  );
+  const visibleDesktopNavTabs = useMemo<PlatformNavTab[]>(
+    () =>
+      isAuthenticated
+        ? PLATFORM_DESKTOP_NAV_TABS
+        : ['home', 'category', 'create', 'projects', 'profile'],
     [isAuthenticated],
   );
   const publicUserCode = buildPublicUserCode(authUi?.user);
@@ -2853,37 +2945,49 @@ export function RpgEntryHomeView({
     () => buildProfileTaskCardSummary(taskCenter),
     [taskCenter],
   );
-  const tabIcons: Record<
-    PlatformHomeTab,
-    ComponentType<{ className?: string }>
-  > = isAuthenticated
-    ? {
-        home: Sparkles,
-        category: Compass,
-        create: Sparkles,
-        saves: Pencil,
-        profile: UserRound,
-      }
-    : {
-        home: Gamepad2,
-        category: Compass,
-        create: Sparkles,
-        saves: Pencil,
-        profile: UserRound,
-      };
+  const tabIcons: Record<PlatformNavTab, ComponentType<{ className?: string }>> =
+    isAuthenticated
+      ? {
+          home: Sparkles,
+          category: Compass,
+          create: Sparkles,
+          projects: FolderKanban,
+          saves: Pencil,
+          profile: UserRound,
+        }
+      : {
+          home: Gamepad2,
+          category: Compass,
+          create: Sparkles,
+          projects: FolderKanban,
+          saves: Pencil,
+          profile: UserRound,
+        };
   const tabLabels = {
     home: '推荐',
     category: '发现',
     create: '创作',
+    projects: '项目',
     saves: '草稿',
     profile: '我的',
-  } as const;
+  } as const satisfies Record<PlatformNavTab, string>;
+  const resolvedDesktopNavTab = activeDesktopNavTab ?? activeTab;
 
   useEffect(() => {
-    if (!visibleTabs.includes(activeTab)) {
+    if (allowHiddenActiveTab) {
+      return;
+    }
+    if (!visibleMobileTabs.includes(activeTab) && !isDesktopLayout) {
       onTabChange(isAuthenticated ? 'home' : 'category');
     }
-  }, [activeTab, isAuthenticated, onTabChange, visibleTabs]);
+  }, [
+    activeTab,
+    allowHiddenActiveTab,
+    isAuthenticated,
+    isDesktopLayout,
+    onTabChange,
+    visibleMobileTabs,
+  ]);
 
   useEffect(() => {
     if (
@@ -4398,6 +4502,11 @@ export function RpgEntryHomeView({
               icon={Settings}
               onClick={() => authUi.openSettingsModal()}
             />
+            <ProfileSettingsRow
+              label="开发者 API Key"
+              icon={KeyRound}
+              onClick={() => setIsApiKeysModalOpen(true)}
+            />
           </section>
 
           <ProfileLegalSection onOpenDocument={setActiveLegalDocumentId} />
@@ -4724,8 +4833,9 @@ export function RpgEntryHomeView({
     saves: savesContent,
     profile: profileContent,
   } satisfies Record<PlatformHomeTab, ReactNode>;
-  const tabPanels = PLATFORM_HOME_TABS.filter((tab) =>
-    visibleTabs.includes(tab),
+  const tabPanels = PLATFORM_HOME_TABS.filter(
+    (tab) =>
+      isDesktopLayout || visibleMobileTabs.includes(tab) || tab === activeTab,
   ).map((tab) => {
     const shouldMountPanel = tab === activeTab || visitedTabs.has(tab);
 
@@ -4854,6 +4964,100 @@ export function RpgEntryHomeView({
       }}
     />
   ) : null;
+  const apiKeysModal: ReactNode = isApiKeysModalOpen ? (
+    <PlatformProfileApiKeysModal
+      onClose={() => setIsApiKeysModalOpen(false)}
+    />
+  ) : null;
+  const desktopBrandLockup: ReactNode = (
+    <span className="creation-home-brand-lockup shrink-0">
+      <img
+        src={CREATION_HOME_TOPBAR_ASSETS.brandMascot}
+        alt=""
+        aria-hidden="true"
+        draggable={false}
+        className="creation-home-brand-lockup__art"
+      />
+      <RpgEntryBrandLogo className="shrink-0" decorative />
+    </span>
+  );
+  const desktopSearchBar: ReactNode = (
+    <PublicCodeSearchBar
+      value={desktopSearchKeyword}
+      onChange={updateDesktopSearchKeyword}
+      onSubmit={submitDesktopSearch}
+      isSearching={!onSearchPublicCode || Boolean(isSearchingPublicCode)}
+      className="max-w-[34rem] flex-1"
+    />
+  );
+  const desktopTopbarActions: ReactNode = (
+    <div className="platform-desktop-topbar__actions flex items-center gap-3">
+      {isAuthenticated ? (
+        <TopbarWalletShortcutButton
+          variant="desktop"
+          balanceLabel={profileDashboardPresentation.walletBalanceWithUnitLabel}
+          onClick={openRechargeOrRewardCodeModal}
+        />
+      ) : null}
+      <button
+        type="button"
+        onClick={openUserSurface}
+        className="platform-desktop-search flex items-center gap-3 px-3 py-2.5 text-left"
+      >
+        <span
+          className="flex h-11 w-11 items-center justify-center overflow-hidden rounded-full text-base font-black text-white"
+          style={{
+            background: 'var(--platform-profile-avatar-fill)',
+            boxShadow: 'var(--platform-profile-avatar-shadow)',
+          }}
+        >
+          {avatarUrl ? (
+            <img src={avatarUrl} alt="" className="h-full w-full object-cover" />
+          ) : (
+            avatarLabel
+          )}
+        </span>
+        <span className="min-w-0">
+          <span className="block truncate text-sm font-semibold text-[var(--platform-text-strong)]">
+            {authUi?.user?.displayName || '登录'}
+          </span>
+          <span className="block truncate text-xs text-[var(--platform-text-soft)]">
+            {authUi?.user ? publicUserCode : '账号入口'}
+          </span>
+        </span>
+      </button>
+    </div>
+  );
+  const desktopRailNav: ReactNode = (
+    <nav className="platform-desktop-rail flex w-[5.8rem] shrink-0 flex-col gap-3 p-3">
+      {visibleDesktopNavTabs.map((tab) => (
+        <DesktopTabButton
+          key={tab}
+          active={resolvedDesktopNavTab === tab}
+          label={tabLabels[tab]}
+          icon={tabIcons[tab]}
+          creationHomeIconSrc={CREATION_HOME_NAV_ICON_SRC[tab]}
+          emphasized={tab === 'create' && resolvedDesktopNavTab === 'create'}
+          showDot={false}
+          disabled={isRechargePaymentConfirmationPending}
+          onClick={() => {
+            if (isRechargePaymentConfirmationPending) {
+              return;
+            }
+            if (tab === 'create') {
+              onOpenCreateTypePicker();
+              return;
+            }
+            if (tab === 'projects') {
+              onOpenProjects?.();
+              return;
+            }
+            onTabChange(tab);
+          }}
+        />
+      ))}
+    </nav>
+  );
 
   if (!isDesktopLayout) {
     const isMobileRecommendTab = activeTab === 'home';
@@ -4910,9 +5114,9 @@ export function RpgEntryHomeView({
 
           <div className="platform-mobile-bottom-dock min-w-0 shrink-0">
             <div
-              className={`platform-bottom-nav grid ${visibleTabs.length === 5 ? 'grid-cols-5' : visibleTabs.length === 4 ? 'grid-cols-4' : visibleTabs.length === 3 ? 'grid-cols-3' : 'grid-cols-2'}`}
+              className={`platform-bottom-nav grid ${visibleMobileTabs.length === 5 ? 'grid-cols-5' : visibleMobileTabs.length === 4 ? 'grid-cols-4' : visibleMobileTabs.length === 3 ? 'grid-cols-3' : 'grid-cols-2'}`}
             >
-              {visibleTabs.map((tab) => (
+              {visibleMobileTabs.map((tab) => (
                 <PlatformTabButton
                   key={tab}
                   active={activeTab === tab}
@@ -4962,6 +5166,7 @@ export function RpgEntryHomeView({
           ) : null}
           {rewardCodeModal}
           {rechargeModal}
+          {apiKeysModal}
           {rechargePaymentResultModal}
           {qrScannerModal}
           {categoryFilterDialog}
@@ -5021,89 +5226,25 @@ export function RpgEntryHomeView({
         className="flex h-full min-h-0 flex-col"
       >
         <div className="flex h-full min-h-0 flex-col">
-          <div className="platform-desktop-shell flex h-full min-h-0 flex-col p-5 xl:p-6">
-            <div className="platform-desktop-topbar flex items-center gap-4 px-5 py-4">
-              <div className="flex min-w-0 flex-1 items-center gap-5">
-                <RpgEntryBrandLogo className="shrink-0" decorative />
-                <PublicCodeSearchBar
-                  value={desktopSearchKeyword}
-                  onChange={updateDesktopSearchKeyword}
-                  onSubmit={submitDesktopSearch}
-                  isSearching={
-                    !onSearchPublicCode || Boolean(isSearchingPublicCode)
-                  }
-                  className="max-w-[34rem] flex-1"
-                />
-              </div>
-
-              <div className="flex items-center gap-3">
-                {isAuthenticated &&
-                (activeTab === 'create' || activeTab === 'saves') ? (
-                  <TopbarWalletShortcutButton
-                    variant="desktop"
-                    balanceLabel={
-                      profileDashboardPresentation.walletBalanceWithUnitLabel
-                    }
-                    onClick={openRechargeOrRewardCodeModal}
-                  />
-                ) : null}
-                <button
-                  type="button"
-                  onClick={openUserSurface}
-                  className="platform-desktop-search flex items-center gap-3 px-3 py-2.5 text-left"
-                >
-                  <span
-                    className="flex h-11 w-11 items-center justify-center overflow-hidden rounded-full text-base font-black text-white"
-                    style={{
-                      background: 'var(--platform-profile-avatar-fill)',
-                      boxShadow: 'var(--platform-profile-avatar-shadow)',
-                    }}
-                  >
-                    {avatarUrl ? (
-                      <img
-                        src={avatarUrl}
-                        alt=""
-                        className="h-full w-full object-cover"
-                      />
-                    ) : (
-                      avatarLabel
-                    )}
-                  </span>
-                  <span className="min-w-0">
-                    <span className="block truncate text-sm font-semibold text-[var(--platform-text-strong)]">
-                      {authUi?.user?.displayName || '登录'}
-                    </span>
-                    <span className="block truncate text-xs text-[var(--platform-text-soft)]">
-                      {authUi?.user ? publicUserCode : '账号入口'}
-                    </span>
-                  </span>
-                </button>
-              </div>
-            </div>
-
-            <div className="mt-5 flex min-h-0 gap-5">
-              <aside className="platform-desktop-rail flex w-[5.8rem] shrink-0 flex-col gap-3 p-3">
-                {visibleTabs.map((tab) => (
-                  <DesktopTabButton
-                    key={tab}
-                    active={activeTab === tab}
-                    label={tabLabels[tab]}
-                    icon={tabIcons[tab]}
-                    emphasized={tab === 'create'}
-                    showDot={tab === 'saves' && hasUnreadDraftUpdate}
-                    disabled={isRechargePaymentConfirmationPending}
-                    onClick={() => {
-                      if (isRechargePaymentConfirmationPending) {
-                        return;
-                      }
-                      onTabChange(tab);
-                    }}
-                  />
-                ))}
+          <div className="platform-desktop-shell platform-desktop-shell--workbench flex h-full min-h-0 flex-col p-5 xl:p-6">
+            <div className="platform-desktop-layout flex min-h-0 flex-1">
+              <aside className="platform-desktop-leftbar flex shrink-0 flex-col">
+                {desktopBrandLockup}
+                {desktopRailNav}
               </aside>
 
-              <div className="platform-tab-panel-stack min-w-0 flex-1">
-                {tabPanels}
+              <div className="platform-desktop-main flex min-w-0 flex-1 flex-col">
+                <div className="platform-desktop-topbar flex items-center gap-4 px-5 py-4">
+                  <div className="platform-desktop-topbar__brand-search flex min-w-0 flex-1 items-center gap-5">
+                    {desktopSearchBar}
+                  </div>
+
+                  {desktopTopbarActions}
+                </div>
+
+                <div className="platform-tab-panel-stack min-w-0 flex-1">
+                  {tabPanels}
+                </div>
               </div>
             </div>
           </div>
@@ -5111,6 +5252,7 @@ export function RpgEntryHomeView({
       </div>
       {rewardCodeModal}
       {rechargeModal}
+      {apiKeysModal}
       {rechargePaymentResultModal}
       {categoryFilterDialog}
       {isTaskCenterOpen ? (
diff --git a/src/hooks/useResolvedAssetReadUrl.test.tsx b/src/hooks/useResolvedAssetReadUrl.test.tsx
index 27147c8d1..ab5efe032 100644
--- a/src/hooks/useResolvedAssetReadUrl.test.tsx
+++ b/src/hooks/useResolvedAssetReadUrl.test.tsx
@@ -4,6 +4,7 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
 import { ResolvedAssetImage } from '../components/ResolvedAssetImage';
+import { useResolvedAssetReadUrl } from './useResolvedAssetReadUrl';
 import {
   clearStoredAccessToken,
   setStoredAccessToken,
@@ -71,6 +72,55 @@ describe('useResolvedAssetReadUrl', () => {
     );
   });
 
+  test('显式 objectKey 会通过 objectKey 换签而不是当作普通路径', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          data: {
+            read: {
+              objectKey: 'oss/editor/private-image.png',
+              signedUrl: 'https://signed.example.com/private-image.png',
+              expiresAt: '2099-01-01T00:10:00Z',
+            },
+          },
+          error: null,
+          meta: {
+            apiVersion: '2026-06-16',
+            routeVersion: '2026-06-16',
+            latencyMs: 1,
+            timestamp: '2099-01-01T00:00:00Z',
+          },
+        }),
+        {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        },
+      ),
+    );
+
+    function ObjectKeyProbe() {
+      const { resolvedUrl } = useResolvedAssetReadUrl('/legacy/public.png', {
+        objectKey: 'oss/editor/private-image.png',
+        refreshKey: 'asset-1',
+      });
+      return <output aria-label="资源地址">{resolvedUrl}</output>;
+    }
+
+    render(<ObjectKeyProbe />);
+
+    await waitFor(() => {
+      expect(screen.getByLabelText('资源地址').textContent).toBe(
+        'https://signed.example.com/private-image.png',
+      );
+    });
+    expect(String(vi.mocked(globalThis.fetch).mock.calls[0]?.[0])).toContain(
+      'objectKey=oss%2Feditor%2Fprivate-image.png',
+    );
+  });
+
   test('无前导斜杠的 generated 私有资源也不会裸写入 img', async () => {
     vi.spyOn(globalThis, 'fetch').mockResolvedValue(
       new Response(
diff --git a/src/hooks/useResolvedAssetReadUrl.ts b/src/hooks/useResolvedAssetReadUrl.ts
index 01e0d8939..a28114a13 100644
--- a/src/hooks/useResolvedAssetReadUrl.ts
+++ b/src/hooks/useResolvedAssetReadUrl.ts
@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 
 import {
+  getSignedAssetReadUrl,
   resolveAssetReadUrl,
   shouldResolveAssetReadUrl,
 } from '../services/assetReadUrlService';
@@ -8,6 +9,7 @@ import {
 type UseResolvedAssetReadUrlOptions = {
   enabled?: boolean;
   expireSeconds?: number;
+  objectKey?: string | null;
   refreshKey?: string | number | null;
 };
 
@@ -17,15 +19,18 @@ export function useResolvedAssetReadUrl(
 ) {
   const enabled = options.enabled !== false;
   const normalizedSource = source?.trim() ?? '';
+  const normalizedObjectKey = options.objectKey?.trim() ?? '';
   const shouldResolve =
-    enabled && shouldResolveAssetReadUrl(normalizedSource);
+    enabled &&
+    (Boolean(normalizedObjectKey) ||
+      shouldResolveAssetReadUrl(normalizedSource));
   const [resolvedUrl, setResolvedUrl] = useState(
     shouldResolve ? '' : normalizedSource,
   );
   const [isResolving, setIsResolving] = useState(shouldResolve);
 
   useEffect(() => {
-    if (!normalizedSource) {
+    if (!normalizedSource && !normalizedObjectKey) {
       setResolvedUrl('');
       setIsResolving(false);
       return;
@@ -42,10 +47,23 @@ export function useResolvedAssetReadUrl(
     setResolvedUrl('');
     setIsResolving(true);
 
-    void resolveAssetReadUrl(normalizedSource, {
-      expireSeconds: options.expireSeconds,
-      refreshKey: options.refreshKey,
-    })
+    const resolvePromise = normalizedObjectKey
+      ? getSignedAssetReadUrl(
+          {
+            objectKey: normalizedObjectKey,
+            expireSeconds: options.expireSeconds,
+          },
+          undefined,
+          {
+            cacheVersion: options.refreshKey,
+          },
+        )
+      : resolveAssetReadUrl(normalizedSource, {
+          expireSeconds: options.expireSeconds,
+          refreshKey: options.refreshKey,
+        });
+
+    void resolvePromise
       .then((nextUrl) => {
         if (!cancelled) {
           setResolvedUrl(nextUrl);
@@ -68,6 +86,7 @@ export function useResolvedAssetReadUrl(
     };
   }, [
     normalizedSource,
+    normalizedObjectKey,
     options.expireSeconds,
     options.refreshKey,
     shouldResolve,
diff --git a/src/index.css b/src/index.css
index 51eed5551..995366226 100644
--- a/src/index.css
+++ b/src/index.css
@@ -1,4 +1,4 @@
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&family=Noto+Serif+SC:wght@400;700&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&family=Noto+Serif+SC:wght@400;700&display=swap');
 @import 'tailwindcss';
 @source not "../dist";
 @source not "../dist_check";
@@ -321,8 +321,8 @@ html[data-mobile-keyboard-open='true'] #root {
 
 .puzzle-clear-card--opening {
   animation: puzzle-clear-card-opening-flip 520ms
-    calc(var(--puzzle-clear-card-index, 0) * 24ms) cubic-bezier(0.2, 0.72, 0.2, 1)
-    both;
+    calc(var(--puzzle-clear-card-index, 0) * 24ms)
+    cubic-bezier(0.2, 0.72, 0.2, 1) both;
 }
 
 .puzzle-clear-card--locked-group-cell {
@@ -440,7 +440,8 @@ html[data-mobile-keyboard-open='true'] #root {
 }
 
 .puzzle-clear-drag-ghost--dropping {
-  animation: puzzle-clear-drag-ghost-drop 180ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
+  animation: puzzle-clear-drag-ghost-drop 180ms cubic-bezier(0.2, 0.8, 0.2, 1)
+    both;
 }
 
 .puzzle-clear-drag-ghost--returning {
@@ -464,15 +465,15 @@ html[data-mobile-keyboard-open='true'] #root {
 }
 
 .puzzle-clear-transition-piece--clear {
-  animation: puzzle-clear-transition-clear-pop 720ms cubic-bezier(0.2, 0.78, 0.2, 1)
-    both;
+  animation: puzzle-clear-transition-clear-pop 720ms
+    cubic-bezier(0.2, 0.78, 0.2, 1) both;
   transform-origin: center;
   will-change: transform, opacity, filter;
 }
 
 .puzzle-clear-transition-piece--drop {
-  animation: puzzle-clear-transition-drop 460ms cubic-bezier(0.18, 0.82, 0.24, 1)
-    both;
+  animation: puzzle-clear-transition-drop 460ms
+    cubic-bezier(0.18, 0.82, 0.24, 1) both;
   animation-delay: var(--puzzle-clear-drop-delay, 0ms);
   will-change: transform, opacity, filter;
 }
@@ -938,14 +939,14 @@ html[data-mobile-keyboard-open='true'] #root {
 
 .platform-ui-shell,
 .platform-ui-shell * {
-  font-family: 'Inter', 'Noto Sans CJK SC', 'WenQuanYi Zen Hei',
-    'PingFang SC', 'Microsoft YaHei', ui-sans-serif, system-ui, sans-serif !important;
+  font-family: 'Inter', 'Noto Sans CJK SC', 'WenQuanYi Zen Hei', 'PingFang SC',
+    'Microsoft YaHei', ui-sans-serif, system-ui, sans-serif !important;
 }
 
 .platform-theme,
 .platform-theme * {
-  font-family: 'Inter', 'Noto Sans CJK SC', 'WenQuanYi Zen Hei',
-    'PingFang SC', 'Microsoft YaHei', ui-sans-serif, system-ui, sans-serif !important;
+  font-family: 'Inter', 'Noto Sans CJK SC', 'WenQuanYi Zen Hei', 'PingFang SC',
+    'Microsoft YaHei', ui-sans-serif, system-ui, sans-serif !important;
 }
 
 .platform-theme {
@@ -960,11 +961,7 @@ html[data-mobile-keyboard-open='true'] #root {
       rgba(240, 203, 169, 0.24),
       transparent 26%
     ),
-    radial-gradient(
-      circle at 92% 8%,
-      rgba(226, 171, 134, 0.2),
-      transparent 22%
-    ),
+    radial-gradient(circle at 92% 8%, rgba(226, 171, 134, 0.2), transparent 22%),
     radial-gradient(
       circle at 54% 100%,
       rgba(204, 117, 76, 0.08),
@@ -2528,7 +2525,8 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   flex: 0 0 auto;
   align-items: center;
   justify-content: center;
-  border: 1px solid color-mix(in srgb, var(--platform-cool-border) 58%, transparent);
+  border: 1px solid
+    color-mix(in srgb, var(--platform-cool-border) 58%, transparent);
   border-radius: 9999px;
   background: color-mix(
     in srgb,
@@ -2547,7 +2545,11 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
 
 .creation-work-card__quick-action-button:hover {
   transform: translateY(-1px);
-  border-color: color-mix(in srgb, var(--platform-cool-border) 78%, transparent);
+  border-color: color-mix(
+    in srgb,
+    var(--platform-cool-border) 78%,
+    transparent
+  );
   background: color-mix(
     in srgb,
     var(--platform-neutral-bg) 72%,
@@ -2969,6 +2971,5041 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   color: var(--platform-text-strong);
 }
 
+.image-editor-stage-shell {
+  background: #ffffff;
+}
+
+.project-gallery-stage-shell {
+  background: #ffffff;
+}
+
+.project-gallery {
+  position: relative;
+  display: flex;
+  min-height: 0;
+  height: 100%;
+  flex-direction: column;
+  overflow: hidden;
+  background: #ffffff;
+  color: #1f2937;
+}
+
+.project-gallery__header {
+  display: flex;
+  min-height: 4.5rem;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  border-bottom: 1px solid #e5e7eb;
+  padding: 0 1.5rem;
+}
+
+.project-gallery__heading {
+  min-width: 0;
+}
+
+.project-gallery__header h1 {
+  margin: 0;
+  color: #111827;
+  font-size: 1.25rem;
+  font-weight: 900;
+}
+
+.project-gallery__header span {
+  display: block;
+  margin-top: 0.2rem;
+  color: #6b7280;
+  font-size: 0.8rem;
+  font-weight: 700;
+}
+
+.project-gallery__header-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+}
+
+.project-gallery__grid {
+  display: grid;
+  min-height: 0;
+  flex: 1;
+  grid-template-columns: repeat(auto-fill, minmax(13rem, 1fr));
+  align-content: start;
+  gap: 1rem;
+  overflow: auto;
+  padding: 1.5rem;
+  padding-bottom: 6.5rem;
+}
+
+.project-gallery__card {
+  position: relative;
+  min-width: 0;
+}
+
+.project-gallery__card-button,
+.project-gallery__new-card {
+  display: grid;
+  width: 100%;
+  min-width: 0;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  color: #111827;
+  text-align: left;
+  box-shadow: 0 12px 28px rgba(15, 23, 42, 0.06);
+  transition:
+    border-color 160ms ease,
+    box-shadow 160ms ease,
+    transform 160ms ease;
+}
+
+.project-gallery__card-button {
+  overflow: hidden;
+}
+
+.project-gallery__card-button:hover,
+.project-gallery__card--selected .project-gallery__card-button,
+.project-gallery__new-card:hover {
+  border-color: rgba(75, 181, 170, 0.58);
+  box-shadow: 0 18px 36px rgba(15, 23, 42, 0.1);
+  transform: translateY(-1px);
+}
+
+.project-gallery__preview {
+  border: 0;
+  border-radius: 0;
+}
+
+.project-gallery__preview-empty {
+  width: 36%;
+  aspect-ratio: 1;
+  border-radius: 0.5rem;
+  background: linear-gradient(135deg, rgba(75, 181, 170, 0.28), transparent 58%),
+    #e5e7eb;
+}
+
+.project-gallery__meta {
+  display: grid;
+  min-width: 0;
+  gap: 0.25rem;
+  padding: 0.8rem;
+}
+
+.project-gallery__meta span:first-child {
+  overflow: hidden;
+  color: #111827;
+  font-size: 0.94rem;
+  font-weight: 860;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.project-gallery__meta span + span {
+  color: #6b7280;
+  font-size: 0.76rem;
+  font-weight: 680;
+}
+
+.project-gallery__card-menu-wrap {
+  position: absolute;
+  right: 0.6rem;
+  bottom: 3.7rem;
+  z-index: 3;
+  opacity: 0;
+  transition: opacity 140ms ease;
+}
+
+.project-gallery__card:hover .project-gallery__card-menu-wrap,
+.project-gallery__card-menu-wrap:focus-within {
+  opacity: 1;
+}
+
+.platform-floating-menu {
+  position: absolute;
+  display: grid;
+  min-width: 7rem;
+  overflow: hidden;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  box-shadow: 0 18px 40px rgba(15, 23, 42, 0.16);
+}
+
+.platform-floating-menu--top-end {
+  right: 0;
+  bottom: 2.4rem;
+}
+
+.platform-floating-menu--top-start {
+  bottom: 2.4rem;
+  left: 0;
+}
+
+.platform-floating-menu--bottom-end {
+  top: calc(100% + 0.45rem);
+  right: 0;
+}
+
+.platform-floating-menu--bottom-start {
+  top: calc(100% + 0.45rem);
+  left: 0;
+}
+
+.platform-floating-menu__item {
+  display: flex;
+  align-items: center;
+  gap: 0.45rem;
+  border: 0;
+  background: transparent;
+  padding: 0.65rem 0.75rem;
+  color: #111827;
+  font-size: 0.82rem;
+  font-weight: 760;
+  text-align: left;
+}
+
+.platform-floating-menu__item:hover {
+  background: #f3f4f6;
+}
+
+.project-gallery__checkbox {
+  position: absolute;
+  top: 0.65rem;
+  right: 0.65rem;
+  display: grid;
+  width: 1.45rem;
+  height: 1.45rem;
+  place-items: center;
+  border: 1px solid rgba(15, 23, 42, 0.18);
+  border-radius: 0.35rem;
+  background: rgba(255, 255, 255, 0.92);
+  color: #238a82;
+}
+
+.platform-batch-action-toolbar {
+  position: absolute;
+  left: 50%;
+  bottom: 1.1rem;
+  z-index: 12;
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  max-width: calc(100% - 2rem);
+  transform: translateX(-50%);
+  border: 1px solid #e5e7eb;
+  border-radius: 0.75rem;
+  background: rgba(255, 255, 255, 0.96);
+  padding: 0.55rem;
+  box-shadow: 0 18px 44px rgba(15, 23, 42, 0.14);
+}
+
+.project-gallery__new-card {
+  place-items: center;
+  align-self: center;
+  justify-self: center;
+  width: min(22rem, calc(100% - 2rem));
+  min-height: 13rem;
+  margin: auto;
+  color: #238a82;
+  font-weight: 860;
+  text-align: center;
+}
+
+.project-gallery__error {
+  flex-shrink: 0;
+  margin: 1rem 1.5rem 0;
+}
+
+.creation-landing {
+  --creation-clay: #c76532;
+  --creation-clay-dark: #914315;
+  --creation-clay-soft: #ead2bf;
+  --creation-ink: #26170f;
+  --creation-muted: #87756a;
+  min-height: 0;
+  flex: 1;
+  overflow: auto;
+  background:
+    linear-gradient(rgba(255, 250, 244, 0.56), rgba(255, 250, 244, 0.56)),
+    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem repeat,
+    linear-gradient(180deg, #fff9f3 0%, #fffdf9 52%, #fff8f0 100%);
+  color: var(--creation-ink);
+}
+
+.creation-landing__hero,
+.creation-landing__section {
+  width: min(1296px, calc(100% - 2rem));
+  margin: 0 auto;
+}
+
+.creation-landing__hero {
+  display: grid;
+  gap: 1.7rem;
+  padding: clamp(3rem, 5.1vw, 4.35rem) 0 1.55rem;
+  text-align: center;
+}
+
+.creation-landing__hero-copy {
+  display: grid;
+  justify-items: center;
+  gap: 1.05rem;
+}
+
+.creation-landing__eyebrow {
+  width: fit-content;
+  color: #8c796c;
+  font-size: clamp(0.86rem, 1.2vw, 1.02rem);
+  font-weight: 860;
+  letter-spacing: 0.56em;
+  text-indent: 0.56em;
+}
+
+.creation-landing__hero h1 {
+  margin: 0;
+  max-width: 62rem;
+  color: var(--creation-ink);
+  font-family:
+    "Songti SC", "STSong", "Noto Serif SC", "SimSun", serif;
+  font-size: clamp(2.35rem, 4.25vw, 3.85rem);
+  font-weight: 950;
+  letter-spacing: 0;
+  line-height: 1.04;
+}
+
+.creation-landing__hero p {
+  margin: 0;
+  color: #8a7466;
+  font-size: clamp(1rem, 1.45vw, 1.28rem);
+  font-weight: 820;
+  letter-spacing: 0.38em;
+  text-indent: 0.38em;
+}
+
+.creation-landing__hero-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 1.05rem;
+  padding-top: 0.9rem;
+}
+
+.creation-landing__hero-action {
+  min-width: 11.4rem;
+  min-height: 3.8rem;
+  border-radius: 1.7rem !important;
+  padding: 0 2rem 0 1.35rem !important;
+  font-size: 1.02rem !important;
+  letter-spacing: 0.08em;
+  box-shadow:
+    0 16px 28px rgba(130, 66, 24, 0.18),
+    inset 0 1px 0 rgba(255, 255, 255, 0.42);
+}
+
+.creation-landing__button-art {
+  width: 2.3rem;
+  height: 2.3rem;
+  flex: 0 0 auto;
+  border-radius: 999px;
+  object-fit: cover;
+  object-position: center;
+  filter: drop-shadow(0 0.14rem 0.16rem rgba(91, 45, 18, 0.18));
+  mix-blend-mode: multiply;
+}
+
+.creation-landing__hero-action--primary {
+  border: 1px solid rgba(157, 74, 22, 0.44) !important;
+  background:
+    radial-gradient(circle at 30% 18%, rgba(255, 194, 128, 0.58), transparent 42%),
+    linear-gradient(180deg, #d97937 0%, #bd5b20 100%) !important;
+  color: #fff9f0 !important;
+}
+
+.creation-landing__hero-action--secondary {
+  border: 1px solid rgba(209, 178, 151, 0.9) !important;
+  background: rgba(255, 250, 244, 0.78) !important;
+  color: #8b5738 !important;
+  box-shadow:
+    0 12px 24px rgba(130, 66, 24, 0.08),
+    inset 0 1px 0 rgba(255, 255, 255, 0.88);
+}
+
+.creation-landing__hero-board {
+  display: none;
+}
+
+.creation-landing__hero-tile {
+  position: absolute;
+  display: block;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.55rem;
+  background: #ffffff;
+  box-shadow: 0 18px 36px rgba(15, 23, 42, 0.1);
+}
+
+.creation-landing__hero-tile--main {
+  left: 14%;
+  top: 14%;
+  width: 58%;
+  aspect-ratio: 4 / 3;
+  background:
+    linear-gradient(135deg, rgba(75, 181, 170, 0.24), transparent 52%),
+    #ffffff;
+}
+
+.creation-landing__hero-tile--side {
+  right: 9%;
+  top: 28%;
+  width: 34%;
+  aspect-ratio: 1;
+  background:
+    linear-gradient(135deg, rgba(246, 171, 76, 0.24), transparent 56%),
+    #ffffff;
+}
+
+.creation-landing__hero-tile--small {
+  left: 30%;
+  bottom: 10%;
+  width: 36%;
+  aspect-ratio: 16 / 9;
+  background:
+    linear-gradient(135deg, rgba(129, 140, 248, 0.2), transparent 56%),
+    #ffffff;
+}
+
+.creation-landing__section {
+  display: grid;
+  gap: 1.25rem;
+  padding: 1.05rem 0;
+}
+
+.creation-landing__section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.creation-landing__section-header h2 {
+  margin: 0;
+  color: var(--creation-ink);
+  font-size: 1.2rem;
+  font-weight: 920;
+  letter-spacing: 0.12em;
+}
+
+.creation-landing__link-button {
+  border: 1px solid rgba(214, 184, 159, 0.86);
+  border-radius: 999px;
+  background: rgba(255, 251, 246, 0.82);
+  padding: 0.56rem 1.05rem;
+  color: #9a5428;
+  font-size: 0.82rem;
+  font-weight: 840;
+  box-shadow: 0 10px 22px rgba(130, 66, 24, 0.06);
+}
+
+.creation-landing__feature-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 1.05rem 1.65rem;
+}
+
+.creation-landing__feature {
+  display: grid;
+  grid-template-columns: minmax(5.6rem, 36%) minmax(0, 1fr);
+  gap: 1rem;
+  align-items: center;
+  min-width: 0;
+  min-height: 9.55rem;
+  border: 1px solid rgba(220, 189, 163, 0.78);
+  border-radius: 1.12rem;
+  background:
+    radial-gradient(circle at 21% 42%, rgba(222, 130, 66, 0.12), transparent 9rem),
+    linear-gradient(135deg, rgba(255, 254, 251, 0.92), rgba(255, 247, 238, 0.82));
+  padding: 1.05rem 1.3rem;
+  box-shadow:
+    0 18px 36px rgba(124, 72, 35, 0.08),
+    inset 0 1px 0 rgba(255, 255, 255, 0.72);
+}
+
+.creation-landing__feature-figure {
+  display: grid;
+  min-width: 0;
+  place-items: center;
+}
+
+.creation-landing__feature-icon {
+  position: relative;
+  display: grid;
+  width: clamp(5.5rem, 8.4vw, 7.1rem);
+  height: clamp(5.5rem, 8.4vw, 7.1rem);
+  place-items: center;
+  border-radius: 1.7rem;
+  background: transparent;
+  color: inherit;
+  transform: rotate(-4deg);
+  box-shadow: none;
+}
+
+.creation-landing__feature-icon::after {
+  position: absolute;
+  right: 10%;
+  bottom: 4%;
+  left: 12%;
+  height: 0.55rem;
+  border-radius: 999px;
+  background: rgba(112, 62, 32, 0.22);
+  filter: blur(0.16rem);
+  content: "";
+}
+
+.creation-landing__feature-art {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  object-position: center;
+  filter: drop-shadow(0 0.5rem 0.5rem rgba(112, 62, 32, 0.16));
+  mix-blend-mode: multiply;
+}
+
+.creation-landing__feature:nth-child(2n) .creation-landing__feature-icon {
+  transform: rotate(3deg);
+  border-radius: 999px 999px 1.4rem 1.4rem;
+}
+
+.creation-landing__feature:nth-child(3n) .creation-landing__feature-icon {
+  transform: rotate(0deg);
+  border-radius: 1.8rem;
+}
+
+.creation-landing__feature-copy {
+  display: grid;
+  min-width: 0;
+  gap: 0.48rem;
+}
+
+.creation-landing__feature h3,
+.creation-landing__asset-card h3 {
+  margin: 0;
+  color: var(--creation-ink);
+  font-size: 1.22rem;
+  font-weight: 880;
+}
+
+.creation-landing__feature p {
+  margin: 0;
+  color: #8a7466;
+  font-size: 0.9rem;
+  font-weight: 650;
+  line-height: 1.55;
+}
+
+.creation-landing__project-row {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(10rem, 1fr));
+  gap: 0.95rem;
+}
+
+.creation-landing__project-card {
+  display: grid;
+  gap: 0.65rem;
+  min-width: 0;
+  border: 1px solid rgba(220, 189, 163, 0.78);
+  border-radius: 1rem;
+  background: rgba(255, 254, 251, 0.84);
+  padding: 0.82rem;
+  color: var(--creation-ink);
+  text-align: left;
+  box-shadow:
+    0 16px 32px rgba(124, 72, 35, 0.08),
+    inset 0 1px 0 rgba(255, 255, 255, 0.72);
+}
+
+.creation-landing__project-card:hover,
+.creation-landing__link-button:hover {
+  border-color: rgba(195, 104, 48, 0.42);
+  box-shadow: 0 18px 36px rgba(124, 72, 35, 0.12);
+}
+
+.creation-landing__project-card--new {
+  place-items: center;
+  min-height: 12rem;
+  color: #9a5428;
+  font-weight: 880;
+  text-align: center;
+}
+
+.creation-landing__project-card--new span {
+  display: grid;
+  width: 5.4rem;
+  height: 5.4rem;
+  place-items: center;
+  border-radius: 1.4rem;
+  background: transparent;
+}
+
+.creation-landing__project-new-art {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  object-position: center;
+  filter: drop-shadow(0 0.42rem 0.42rem rgba(112, 62, 32, 0.16));
+  mix-blend-mode: multiply;
+}
+
+.creation-landing__project-cover {
+  border-radius: 0.72rem;
+}
+
+.creation-landing__project-meta {
+  display: grid;
+  gap: 0.2rem;
+}
+
+.creation-landing__project-meta strong,
+.creation-landing__project-meta small {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.creation-landing__project-meta strong {
+  font-size: 0.88rem;
+}
+
+.creation-landing__project-meta small {
+  color: var(--creation-muted);
+  font-size: 0.74rem;
+  font-weight: 700;
+}
+
+.creation-landing__tabs {
+  display: flex;
+  gap: 0.45rem;
+  overflow-x: auto;
+  padding-bottom: 0.15rem;
+}
+
+.creation-landing__tab {
+  flex: 0 0 auto;
+  border: 1px solid rgba(220, 189, 163, 0.78);
+  border-radius: 999px;
+  background: rgba(255, 254, 251, 0.82);
+  padding: 0.48rem 0.8rem;
+  color: #8a7466;
+  font-size: 0.82rem;
+  font-weight: 820;
+}
+
+.creation-landing__tab--active {
+  border-color: rgba(195, 104, 48, 0.42);
+  background: #f2d8c0;
+  color: #8a451d;
+}
+
+.creation-landing__asset-waterfall {
+  column-count: 3;
+  column-gap: 0.92rem;
+}
+
+.creation-landing__asset-card {
+  display: inline-block;
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+  margin: 0 0 0.92rem;
+  break-inside: avoid;
+  border: 1px solid rgba(220, 189, 163, 0.78);
+  border-radius: 1rem;
+  background: rgba(255, 254, 251, 0.88);
+  padding: 0;
+  color: inherit;
+  text-align: left;
+  box-shadow: 0 16px 32px rgba(124, 72, 35, 0.1);
+  cursor: zoom-in;
+}
+
+.creation-landing__asset-card:hover {
+  border-color: rgba(195, 104, 48, 0.46);
+  box-shadow: 0 20px 40px rgba(124, 72, 35, 0.14);
+}
+
+.creation-landing__asset-preview {
+  position: relative;
+  display: grid;
+  min-height: 9.5rem;
+  max-height: 23rem;
+  overflow: hidden;
+  place-items: center;
+  background: linear-gradient(180deg, #fffdfa, #fff4ea);
+}
+
+.creation-landing__asset-preview--bundle {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: stretch;
+  gap: 0.18rem;
+  padding: 0.18rem;
+}
+
+.creation-landing__asset-preview-tile {
+  position: relative;
+  display: grid;
+  width: 100%;
+  height: 100%;
+  min-height: 5rem;
+  overflow: hidden;
+  place-items: center;
+  border-radius: 0.72rem;
+  background: rgba(255, 255, 255, 0.66);
+}
+
+.creation-landing__asset-preview-more {
+  position: absolute;
+  right: 0.65rem;
+  bottom: 0.65rem;
+  display: inline-flex;
+  min-width: 2rem;
+  height: 2rem;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  background: rgba(44, 31, 22, 0.72);
+  color: #fffdf9;
+  font-size: 0.78rem;
+  font-weight: 850;
+}
+
+.creation-landing__asset-audio-preview {
+  display: grid;
+  width: 100%;
+  height: 100%;
+  min-height: 8rem;
+  place-items: center;
+  gap: 1rem;
+  padding: 1rem;
+  background:
+    linear-gradient(135deg, rgba(244, 187, 129, 0.4), rgba(255, 247, 236, 0.92)),
+    radial-gradient(circle at 30% 24%, rgba(255, 255, 255, 0.9), transparent 42%);
+  color: #9a5428;
+}
+
+.creation-landing__asset-audio-preview svg {
+  width: 2.6rem;
+  height: 2.6rem;
+}
+
+.creation-landing__asset-audio-preview audio {
+  width: min(100%, 28rem);
+}
+
+.creation-landing__asset-meta {
+  display: grid;
+  gap: 0.55rem;
+  padding: 0.85rem;
+}
+
+.creation-landing__asset-meta p {
+  display: -webkit-box;
+  min-height: 2.6em;
+  overflow: hidden;
+  margin: 0;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  color: var(--creation-muted);
+  font-size: 0.8rem;
+  font-weight: 650;
+  line-height: 1.3;
+}
+
+.creation-landing__asset-meta dl {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.6rem;
+  margin: 0;
+}
+
+.creation-landing__asset-meta div {
+  min-width: 0;
+}
+
+.creation-landing__asset-meta dt {
+  color: #aa9588;
+  font-size: 0.68rem;
+  font-weight: 760;
+}
+
+.creation-landing__asset-meta dd {
+  overflow: hidden;
+  margin: 0;
+  color: var(--creation-ink);
+  font-size: 0.78rem;
+  font-weight: 780;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.creation-landing__showcase-modal-overlay {
+  padding: 0.5rem;
+  background: rgba(11, 8, 6, 0.82);
+}
+
+.creation-landing__showcase-modal-panel {
+  width: min(100vw - 1rem, 88rem);
+  height: min(96vh, 64rem);
+  max-height: calc(100vh - 1rem);
+  overflow: hidden;
+  border-radius: 1.2rem;
+  background: #100d0b;
+  box-shadow: 0 30px 90px rgba(0, 0, 0, 0.5);
+}
+
+.creation-landing__showcase-modal-body {
+  display: flex;
+  min-height: 0;
+  flex: 1;
+  padding: 0;
+  overflow: hidden;
+}
+
+.creation-landing__showcase-modal {
+  position: relative;
+  display: grid;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  grid-template-rows: minmax(0, 1fr) auto;
+  overflow: hidden;
+  background:
+    radial-gradient(circle at 18% 12%, rgba(186, 117, 65, 0.18), transparent 32%),
+    #100d0b;
+}
+
+.creation-landing__showcase-modal-close {
+  z-index: 4;
+}
+
+.creation-landing__showcase-modal-stage {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  min-height: 0;
+  overflow: hidden;
+  place-items: center;
+  padding: clamp(1rem, 3vw, 2.5rem);
+}
+
+.creation-landing__showcase-current {
+  position: relative;
+  display: grid;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+  place-items: center;
+}
+
+.creation-landing__showcase-current > img,
+.creation-landing__showcase-current > video,
+.creation-landing__showcase-current .creation-landing__asset-audio-preview {
+  max-width: 100%;
+  max-height: 100%;
+  border-radius: 0.9rem;
+}
+
+.creation-landing__showcase-current > img,
+.creation-landing__showcase-current > video {
+  width: auto;
+  height: auto;
+  object-fit: contain;
+  object-position: center;
+  box-shadow: 0 18px 52px rgba(0, 0, 0, 0.32);
+}
+
+.creation-landing__showcase-current > .creation-landing__showcase-media {
+  display: block;
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+  object-position: center;
+}
+
+.creation-landing__showcase-dock {
+  position: relative;
+  z-index: 3;
+  display: grid;
+  gap: 0.85rem;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+  background: rgba(24, 18, 14, 0.94);
+  backdrop-filter: none;
+  padding: 0.85rem;
+}
+
+.creation-landing__showcase-dock-meta {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(13rem, 0.44fr);
+  gap: 0.75rem 1rem;
+  align-items: start;
+  color: #fff8ef;
+}
+
+.creation-landing__showcase-dock-meta h3 {
+  margin: 0;
+  overflow: hidden;
+  color: #fff8ef;
+  font-size: 1rem;
+  font-weight: 860;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.creation-landing__showcase-dock-meta p {
+  grid-column: 1 / 2;
+  display: -webkit-box;
+  min-height: 2.6em;
+  overflow: hidden;
+  margin: 0;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  color: rgba(255, 248, 239, 0.72);
+  font-size: 0.82rem;
+  font-weight: 620;
+  line-height: 1.32;
+}
+
+.creation-landing__showcase-dock-meta dl {
+  display: grid;
+  grid-column: 2 / 3;
+  grid-row: 1 / span 2;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.55rem;
+  margin: 0;
+}
+
+.creation-landing__showcase-dock-meta div {
+  min-width: 0;
+}
+
+.creation-landing__showcase-dock-meta dt {
+  color: rgba(255, 248, 239, 0.5);
+  font-size: 0.68rem;
+  font-weight: 780;
+}
+
+.creation-landing__showcase-dock-meta dd {
+  overflow: hidden;
+  margin: 0;
+  color: #fff8ef;
+  font-size: 0.82rem;
+  font-weight: 820;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.creation-landing__showcase-thumbs {
+  display: flex;
+  gap: 0.55rem;
+  overflow-x: auto;
+  padding-bottom: 0.1rem;
+}
+
+.creation-landing__showcase-thumb {
+  display: grid;
+  flex: 0 0 6.5rem;
+  min-width: 0;
+  gap: 0.38rem;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 0.72rem;
+  background: rgba(255, 255, 255, 0.06);
+  padding: 0.38rem;
+  color: rgba(255, 248, 239, 0.72);
+  font-size: 0.68rem;
+  font-weight: 760;
+  text-align: center;
+}
+
+.creation-landing__showcase-thumb--active {
+  border-color: rgba(242, 184, 124, 0.8);
+  background: rgba(242, 184, 124, 0.18);
+  color: #fff8ef;
+}
+
+.creation-landing__showcase-thumb-media {
+  display: grid;
+  height: 4.1rem;
+  overflow: hidden;
+  place-items: center;
+  border-radius: 0.52rem;
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.creation-landing__showcase-thumb-media svg {
+  width: 1.45rem;
+  height: 1.45rem;
+}
+
+.creation-landing__showcase-thumb > span:last-child {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@media (max-width: 900px) {
+  .creation-landing__hero,
+  .creation-landing__section {
+    width: min(100% - 1.4rem, 42rem);
+  }
+
+  .creation-landing__hero {
+    padding-top: 2.2rem;
+  }
+
+  .creation-landing__hero h1 {
+    max-width: 38rem;
+    font-size: clamp(2rem, 7.6vw, 3.1rem);
+    text-wrap: balance;
+  }
+
+  .creation-landing__feature-grid {
+    grid-template-columns: 1fr;
+    gap: 0.85rem;
+  }
+
+  .creation-landing__feature {
+    min-height: 7.8rem;
+    grid-template-columns: 5.2rem minmax(0, 1fr);
+    padding: 0.9rem 1rem;
+  }
+
+  .creation-landing__feature-icon {
+    width: 4.65rem;
+    height: 4.65rem;
+  }
+
+  .creation-landing__feature h3 {
+    font-size: 1.05rem;
+  }
+
+  .creation-landing__project-row {
+    grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
+  }
+
+  .creation-landing__asset-waterfall {
+    column-count: 2;
+  }
+
+  .creation-landing__showcase-modal-panel {
+    width: calc(100vw - 0.7rem);
+    height: calc(100vh - 0.7rem);
+  }
+
+  .creation-landing__showcase-dock-meta {
+    grid-template-columns: 1fr;
+  }
+
+  .creation-landing__showcase-dock-meta p,
+  .creation-landing__showcase-dock-meta dl {
+    grid-column: auto;
+    grid-row: auto;
+  }
+}
+
+@media (max-width: 560px) {
+  .creation-landing__hero {
+    gap: 1.25rem;
+    padding-top: 1.6rem;
+  }
+
+  .creation-landing__eyebrow,
+  .creation-landing__hero p {
+    letter-spacing: 0.18em;
+    text-indent: 0.18em;
+  }
+
+  .creation-landing__hero-actions {
+    gap: 0.72rem;
+  }
+
+  .creation-landing__hero h1 {
+    font-size: clamp(1.72rem, 7.4vw, 2.05rem);
+    line-height: 1.08;
+  }
+
+  .creation-landing__hero-action {
+    width: min(100%, 14rem);
+    min-height: 3.25rem;
+  }
+
+  .creation-landing__feature {
+    grid-template-columns: 4.55rem minmax(0, 1fr);
+    border-radius: 0.95rem;
+  }
+
+  .creation-landing__feature-icon {
+    width: 4rem;
+    height: 4rem;
+  }
+
+  .creation-landing__section-header {
+    align-items: flex-start;
+  }
+
+  .creation-landing__asset-waterfall {
+    column-count: 1;
+  }
+
+  .creation-landing__showcase-modal-overlay {
+    padding: 0;
+  }
+
+  .creation-landing__showcase-modal-panel {
+    width: 100vw;
+    height: 100vh;
+    max-height: 100vh;
+    border-radius: 0;
+  }
+
+  .creation-landing__showcase-modal-stage {
+    padding: 3.2rem 0.75rem 0.75rem;
+  }
+
+  .creation-landing__showcase-dock {
+    padding: 0.72rem;
+  }
+
+  .creation-landing__showcase-thumb {
+    flex-basis: 5.7rem;
+  }
+}
+
+.image-canvas-editor {
+  position: relative;
+  display: flex;
+  min-height: 0;
+  min-width: 0;
+  height: 100%;
+  gap: 0;
+  overflow: hidden;
+  background: #ffffff;
+  color: #1f2937;
+  -webkit-touch-callout: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.image-editor-creation-entry-stack {
+  display: grid;
+  min-width: 0;
+  gap: 0.8rem;
+}
+
+.image-editor-creation-entry {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-height: 4.4rem;
+  width: 100%;
+  border: 1px solid rgba(75, 181, 170, 0.22);
+  border-radius: 0.5rem;
+  background: linear-gradient(
+      135deg,
+      rgba(75, 181, 170, 0.16),
+      rgba(223, 161, 94, 0.1)
+    ),
+    var(--platform-subpanel-fill);
+  padding: 0.7rem;
+  color: var(--platform-text-strong);
+  text-align: left;
+  box-shadow: 0 16px 32px rgba(43, 68, 64, 0.12);
+  transition:
+    transform 180ms ease,
+    border-color 180ms ease,
+    box-shadow 180ms ease;
+}
+
+.image-editor-creation-entry:hover {
+  transform: translateY(-1px);
+  border-color: rgba(75, 181, 170, 0.5);
+  box-shadow: 0 20px 38px rgba(43, 68, 64, 0.16);
+}
+
+.image-editor-creation-entry__icon {
+  display: grid;
+  width: 2.7rem;
+  height: 2.7rem;
+  flex-shrink: 0;
+  place-items: center;
+  border-radius: 0.45rem;
+  background: rgba(75, 181, 170, 0.18);
+  color: #238a82;
+}
+
+.image-editor-creation-entry__body {
+  display: grid;
+  min-width: 0;
+  gap: 0.15rem;
+}
+
+.image-editor-creation-entry__body span:first-child {
+  font-size: 0.98rem;
+  font-weight: 900;
+}
+
+.image-editor-creation-entry__body span + span {
+  color: var(--platform-text-soft);
+  font-size: 0.76rem;
+  font-weight: 760;
+}
+
+.image-canvas-editor__sidebar {
+  display: flex;
+  width: min(18.5rem, 34vw);
+  min-width: 15.5rem;
+  flex-direction: column;
+  overflow: hidden;
+  border-right: 1px solid #d9dee8;
+  background: #ffffff;
+}
+
+.image-canvas-editor__sidebar-header {
+  display: flex;
+  min-height: 3.4rem;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  border-bottom: 1px solid #d9dee8;
+  padding: 0.65rem;
+}
+
+.image-canvas-editor__sidebar-title,
+.image-canvas-editor__title-block h1 {
+  margin: 0;
+  font-size: 0.9rem;
+  font-weight: 850;
+  letter-spacing: 0;
+}
+
+.image-canvas-editor__sidebar-count,
+.image-canvas-editor__title-block span {
+  display: block;
+  color: #64748b;
+  font-size: 0.72rem;
+  font-weight: 750;
+}
+
+.image-canvas-editor__icon-button,
+.image-canvas-editor__project-back-button,
+.image-canvas-editor__floating-toolbar button,
+.image-canvas-editor__bottom-toolbar button,
+.image-canvas-editor__reset-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid #d9dee8;
+  background: #ffffff;
+  color: #334155;
+  transition:
+    transform 160ms ease,
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease;
+}
+
+.image-canvas-editor__icon-button:hover,
+.image-canvas-editor__floating-toolbar button:hover,
+.image-canvas-editor__bottom-toolbar button:hover,
+.image-canvas-editor__reset-button:hover {
+  transform: translateY(-1px);
+  border-color: #8fb8ff;
+  background: #eef5ff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__icon-button {
+  width: 2.2rem;
+  height: 2.2rem;
+  flex-shrink: 0;
+  border-radius: 0.45rem;
+}
+
+.image-canvas-editor__sidebar-header-actions {
+  display: inline-flex;
+  gap: 0.35rem;
+}
+
+.image-canvas-editor__asset-list {
+  position: relative;
+  display: grid;
+  min-height: 0;
+  align-content: start;
+  gap: 0.7rem;
+  overflow-y: auto;
+  padding: 0.65rem;
+}
+
+.image-canvas-editor__asset-folder {
+  display: grid;
+  gap: 0.45rem;
+}
+
+.image-canvas-editor__asset-folder-header {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  gap: 0.35rem;
+  color: #475569;
+  font-size: 0.76rem;
+  font-weight: 850;
+}
+
+.image-canvas-editor__asset-folder-header > span:first-of-type,
+.image-canvas-editor__folder-rename-input {
+  min-width: 0;
+  flex: 1;
+}
+
+.image-canvas-editor__folder-rename-input {
+  height: 1.8rem;
+  border: 1px solid #8fb8ff;
+  border-radius: 0.35rem;
+  background: #ffffff;
+  padding: 0 0.45rem;
+  color: #1f2937;
+  font: inherit;
+  font-size: 0.76rem;
+  outline: none;
+}
+
+.image-canvas-editor__asset-folder-header button {
+  display: inline-flex;
+  width: 1.8rem;
+  height: 1.8rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid transparent;
+  border-radius: 0.36rem;
+  background: transparent;
+  color: #64748b;
+}
+
+.image-canvas-editor__asset-folder-header button:hover {
+  border-color: #d9dee8;
+  background: #f8fafc;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__asset-folder-header span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__asset-folder-header span + span {
+  color: #94a3b8;
+  font-size: 0.7rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__asset-folder--move-target
+  > .image-canvas-editor__asset-folder-header {
+  border-color: #93c5fd;
+  background: #eff6ff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__asset-folder-sticky-target {
+  position: sticky;
+  top: 0;
+  z-index: 8;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.45rem;
+  border: 1px solid #93c5fd;
+  border-radius: 0.45rem;
+  background: #eff6ff;
+  padding: 0.38rem 0.5rem;
+  color: #1d4ed8;
+  font-size: 0.78rem;
+  font-weight: 880;
+  box-shadow: 0 10px 24px rgba(37, 99, 235, 0.12);
+}
+
+.image-canvas-editor__asset-folder-sticky-target span {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__asset-folder-list {
+  display: grid;
+  gap: 0.5rem;
+}
+
+.image-canvas-editor__asset-row {
+  display: grid;
+  grid-template-columns: 4.4rem minmax(0, 1fr) auto;
+  min-height: 5.1rem;
+  gap: 0.55rem;
+  align-items: center;
+  border: 1px solid #e2e8f0;
+  border-radius: 0.45rem;
+  background: #f8fafc;
+  padding: 0.45rem;
+  color: #1f2937;
+  transition:
+    transform 160ms ease,
+    border-color 160ms ease,
+    background-color 160ms ease;
+}
+
+.image-canvas-editor__asset-row:hover {
+  transform: translateY(-1px);
+  border-color: #8fb8ff;
+  background: #eef5ff;
+}
+
+.image-canvas-editor__asset-row--selected {
+  border-color: #2563eb;
+  background: #dbeafe;
+}
+
+.image-canvas-editor__asset-row--uploading {
+  border-color: #bfdbfe;
+  background: #f8fbff;
+}
+
+.image-canvas-editor__asset-row--uploading:hover {
+  transform: none;
+  border-color: #93c5fd;
+  background: #f8fbff;
+}
+
+.image-canvas-editor__asset-row--upload-failed {
+  border-color: #fecaca;
+  background: #fff7f7;
+}
+
+.image-canvas-editor__asset-drag-preview {
+  position: fixed;
+  z-index: 80;
+  max-width: 11rem;
+  transform: translate(-50%, -50%);
+  border: 1px solid #bfdbfe;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.96);
+  padding: 0.4rem 0.65rem;
+  color: #1d4ed8;
+  font-size: 0.78rem;
+  font-weight: 880;
+  pointer-events: none;
+  box-shadow: 0 14px 34px rgba(15, 23, 42, 0.18);
+}
+
+.image-canvas-editor__asset-upload-overlay {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  background: rgba(248, 250, 252, 0.74);
+  color: #1d4ed8;
+  font-size: 0.72rem;
+  font-weight: 880;
+}
+
+.image-canvas-editor__asset-upload-progress {
+  grid-column: 1 / -1;
+  display: grid;
+  gap: 0.25rem;
+  color: #64748b;
+  font-size: 0.72rem;
+  font-weight: 780;
+}
+
+.image-canvas-editor__asset-upload-progress > div {
+  display: flex;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.image-canvas-editor__asset-upload-progress progress {
+  width: 100%;
+  height: 0.35rem;
+  overflow: hidden;
+  border: 0;
+  border-radius: 999px;
+}
+
+.image-canvas-editor__asset-upload-progress progress::-webkit-progress-bar {
+  background: #e2e8f0;
+}
+
+.image-canvas-editor__asset-upload-progress progress::-webkit-progress-value {
+  background: #2563eb;
+}
+
+.image-canvas-editor__asset-batch-toolbar {
+  position: sticky;
+  bottom: 0;
+  justify-content: center;
+  margin-top: 0.35rem;
+}
+
+.image-canvas-editor__asset-marquee {
+  position: absolute;
+  z-index: 4;
+  border: 1px solid #2563eb;
+  background: rgb(37 99 235 / 0.12);
+  pointer-events: none;
+}
+
+.image-canvas-editor__canvas-marquee {
+  position: absolute;
+  z-index: 7;
+  border: 1px solid #2563eb;
+  background: rgb(37 99 235 / 0.12);
+  pointer-events: none;
+}
+
+.image-canvas-editor__upload-drop-overlay {
+  position: absolute;
+  z-index: 30;
+  display: grid;
+  place-items: center;
+  align-content: center;
+  gap: 0.25rem;
+  border: 1px dashed #60a5fa;
+  background: rgba(239, 246, 255, 0.72);
+  color: #1d4ed8;
+  text-align: center;
+  pointer-events: none;
+  backdrop-filter: blur(2px);
+}
+
+.image-canvas-editor__upload-drop-overlay span {
+  font-size: 0.82rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__upload-drop-overlay strong {
+  font-size: 1rem;
+  font-weight: 920;
+}
+
+.image-canvas-editor__upload-drop-overlay--assets {
+  inset: 0.45rem;
+  border-radius: 0.55rem;
+}
+
+.image-canvas-editor__upload-drop-overlay--canvas {
+  inset: 0.85rem;
+  border-radius: 0.65rem;
+}
+
+.image-canvas-editor__asset-button {
+  display: block;
+  border: 0;
+  background: transparent;
+  padding: 0;
+}
+
+.image-canvas-editor__layer-row-button {
+  display: block;
+  border: 0;
+  background: transparent;
+  padding: 0;
+}
+
+.image-canvas-editor__asset-thumb {
+  display: block;
+  overflow: hidden;
+  aspect-ratio: 1;
+  border-radius: 0.35rem;
+  background: linear-gradient(
+      45deg,
+      rgba(148, 163, 184, 0.18) 25%,
+      transparent 25%
+    ),
+    linear-gradient(-45deg, rgba(148, 163, 184, 0.18) 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, rgba(148, 163, 184, 0.18) 75%),
+    linear-gradient(-45deg, transparent 75%, rgba(148, 163, 184, 0.18) 75%);
+  background-position:
+    0 0,
+    0 0.5rem,
+    0.5rem -0.5rem,
+    -0.5rem 0;
+  background-size: 1rem 1rem;
+}
+
+.image-canvas-editor__asset-media-overlay {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  color: #f8fafc;
+}
+
+.image-canvas-editor__media-preview {
+  position: relative;
+  isolation: isolate;
+  background:
+    radial-gradient(circle at 25% 24%, rgba(255, 255, 255, 0.22), transparent 0.72rem),
+    linear-gradient(135deg, rgba(15, 23, 42, 0.84), rgba(20, 83, 45, 0.58));
+}
+
+.image-canvas-editor__media-preview::before {
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  content: '';
+  opacity: 0.72;
+}
+
+.image-canvas-editor__media-preview--audio::before {
+  background:
+    repeating-linear-gradient(
+      90deg,
+      rgba(103, 232, 249, 0.34) 0 0.18rem,
+      transparent 0.18rem 0.52rem
+    ),
+    linear-gradient(135deg, rgba(14, 116, 144, 0.42), rgba(49, 46, 129, 0.48));
+}
+
+.image-canvas-editor__media-preview--video::before {
+  background:
+    linear-gradient(90deg, rgba(15, 23, 42, 0.42) 0 14%, transparent 14% 86%, rgba(15, 23, 42, 0.42) 86%),
+    repeating-linear-gradient(
+      0deg,
+      rgba(248, 250, 252, 0.34) 0 0.2rem,
+      transparent 0.2rem 0.58rem
+    ),
+    linear-gradient(135deg, rgba(124, 58, 237, 0.38), rgba(20, 184, 166, 0.38));
+}
+
+.image-canvas-editor__media-preview--variant-1 {
+  filter: hue-rotate(22deg);
+}
+
+.image-canvas-editor__media-preview--variant-2 {
+  filter: hue-rotate(54deg);
+}
+
+.image-canvas-editor__media-preview--variant-3 {
+  filter: hue-rotate(92deg);
+}
+
+.image-canvas-editor__media-preview--variant-4 {
+  filter: hue-rotate(138deg);
+}
+
+.image-canvas-editor__media-preview--variant-5 {
+  filter: hue-rotate(184deg);
+}
+
+.image-canvas-editor__layer img,
+.image-canvas-editor__layer video {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.image-canvas-editor__asset-meta {
+  display: grid;
+  min-width: 0;
+  gap: 0.2rem;
+  font-size: 0.84rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__asset-meta span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__asset-rename-input {
+  min-width: 0;
+  height: 1.8rem;
+  border: 1px solid #8fb8ff;
+  border-radius: 0.35rem;
+  background: #ffffff;
+  padding: 0 0.45rem;
+  color: #1f2937;
+  font: inherit;
+  font-size: 0.78rem;
+  outline: none;
+}
+
+.image-canvas-editor__asset-actions {
+  display: inline-flex;
+  gap: 0.22rem;
+}
+
+.image-canvas-editor__asset-actions button,
+.image-canvas-editor__folder-create button {
+  display: inline-flex;
+  width: 1.9rem;
+  height: 1.9rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid #d9dee8;
+  border-radius: 0.42rem;
+  background: #ffffff;
+  color: #475569;
+}
+
+.image-canvas-editor__asset-actions button:hover,
+.image-canvas-editor__folder-create button:hover {
+  border-color: #8fb8ff;
+  background: #ffffff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__folder-create {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 0.35rem;
+  border: 1px solid #d9dee8;
+  border-radius: 0.45rem;
+  background: #f8fafc;
+  padding: 0.4rem;
+}
+
+.image-canvas-editor__folder-create-input {
+  min-width: 0;
+  height: 2rem;
+  border: 1px solid #8fb8ff;
+  border-radius: 0.35rem;
+  background: #ffffff;
+  padding: 0 0.5rem;
+  color: #1f2937;
+  font: inherit;
+  font-size: 0.78rem;
+  font-weight: 800;
+  outline: none;
+}
+
+.image-canvas-editor__asset-meta span + span {
+  color: #64748b;
+  font-size: 0.82rem;
+  font-weight: 760;
+}
+
+.image-canvas-editor__layers-list {
+  display: grid;
+  min-height: 0;
+  align-content: start;
+  gap: 0.45rem;
+  overflow-y: auto;
+  padding: 0.65rem;
+}
+
+.image-canvas-editor__layer-row {
+  display: grid;
+  grid-template-columns: 2.7rem minmax(0, 1fr);
+  min-height: 3.45rem;
+  align-items: center;
+  gap: 0.55rem;
+  border: 1px solid #e2e8f0;
+  border-radius: 0.45rem;
+  background: #f8fafc;
+  padding: 0.38rem;
+  color: #1f2937;
+  text-align: left;
+  transition:
+    border-color 160ms ease,
+    background-color 160ms ease;
+}
+
+.image-canvas-editor__layer-row:hover,
+.image-canvas-editor__layer-row--selected {
+  border-color: #8fb8ff;
+  background: #eef5ff;
+}
+
+.image-canvas-editor__layer-row-thumb {
+  display: block;
+  overflow: hidden;
+  width: 2.7rem;
+  height: 2.7rem;
+  border-radius: 0.35rem;
+  background: #e2e8f0;
+}
+
+.image-canvas-editor__layer-row-meta {
+  display: grid;
+  min-width: 0;
+  gap: 0.18rem;
+  font-size: 0.78rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__layer-row-meta span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__layer-row-meta span + span {
+  color: #64748b;
+  font-size: 0.68rem;
+  font-weight: 760;
+}
+
+.image-canvas-editor__main {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex: 1;
+  flex-direction: column;
+  overflow: hidden;
+  background: #ffffff;
+}
+
+.image-canvas-editor__topbar {
+  display: flex;
+  min-height: 3.4rem;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  border-bottom: 1px solid #d9dee8;
+  background: #ffffff;
+  padding: 0.55rem 0.7rem;
+}
+
+.image-canvas-editor__topbar-actions {
+  display: inline-flex;
+  min-width: 0;
+  flex: 0 1 auto;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.45rem;
+}
+
+.image-canvas-editor__project-back-button {
+  width: 2.25rem;
+  height: 2.25rem;
+  flex: 0 0 auto;
+  border-radius: 0.45rem;
+  text-decoration: none;
+}
+
+.image-canvas-editor__project-title-row {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.image-canvas-editor__project-title-button {
+  min-width: 0;
+  max-width: min(24rem, 42vw);
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: inherit;
+  text-align: left;
+  cursor: text;
+}
+
+.image-canvas-editor__project-title-button h1 {
+  overflow: hidden;
+  max-width: 100%;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__project-rename-button {
+  opacity: 0;
+  transition: opacity 140ms ease;
+}
+
+.image-canvas-editor__project-title-row:hover
+  .image-canvas-editor__project-rename-button,
+.image-canvas-editor__project-rename-button:focus-visible {
+  opacity: 1;
+}
+
+.image-canvas-editor__project-title-form {
+  display: inline-flex;
+  min-width: 0;
+  max-width: min(34rem, 58vw);
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.image-canvas-editor__project-title-input {
+  width: clamp(9rem, 28vw, 18rem);
+}
+
+.image-canvas-editor__project-title-error {
+  max-width: 10rem;
+  overflow: hidden;
+  color: #dc2626;
+  font-size: 0.82rem;
+  font-weight: 760;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__zoom-menu-wrap {
+  margin-left: auto;
+  position: relative;
+  z-index: 20;
+  display: inline-flex;
+  align-items: center;
+}
+
+.image-canvas-editor__zoom-trigger {
+  min-width: 4.15rem;
+  height: 2.25rem;
+  border: 1px solid #d9dee8;
+  border-radius: 0.45rem;
+  background: #ffffff;
+  padding: 0 0.65rem;
+  color: #334155;
+  font-size: 0.78rem;
+  font-weight: 850;
+}
+
+.image-canvas-editor__zoom-trigger:hover {
+  transform: translateY(-1px);
+  border-color: #8fb8ff;
+  background: #eef5ff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__zoom-menu-item {
+  min-width: 12rem;
+  justify-content: flex-start;
+  min-height: 2rem;
+  width: 100%;
+  border-radius: 0.38rem;
+  padding: 0 0.65rem;
+  font-size: 0.76rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__floating-toolbar button,
+.image-canvas-editor__bottom-toolbar button,
+.image-canvas-editor__reset-button {
+  width: 2.25rem;
+  height: 2.25rem;
+  border-radius: 0.45rem;
+}
+
+.image-canvas-editor__bottom-tool-group {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.image-canvas-editor__bottom-toolbar-divider,
+.image-canvas-editor__floating-toolbar-divider {
+  display: inline-block;
+  width: 1px;
+  height: 0.5rem;
+  flex: 0 0 auto;
+  align-self: center;
+  border-radius: 999px;
+  background: #d9dee8;
+}
+
+.image-canvas-editor__floating-toolbar-divider {
+  height: 1.125rem;
+}
+
+.image-canvas-editor__bottom-toolbar-option-wrap {
+  display: inline-flex;
+}
+
+.image-canvas-editor__viewport {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  flex: 1;
+  overflow: hidden;
+  cursor: default;
+  background-color: #f8fafc;
+  touch-action: none;
+}
+
+.image-canvas-editor__viewport--panning {
+  cursor: grabbing;
+}
+
+.image-canvas-editor__viewport--tool-hand {
+  cursor: grab;
+}
+
+.image-canvas-editor__world {
+  position: absolute;
+  left: 0;
+  top: 0;
+  transform-origin: 0 0;
+}
+
+.image-canvas-editor__layer {
+  position: absolute;
+  display: block;
+  overflow: visible;
+  border: 2px solid transparent;
+  border-radius: 0.15rem;
+  background: transparent;
+  padding: 0;
+  cursor: move;
+}
+
+.image-canvas-editor__layer img,
+.image-canvas-editor__layer video {
+  display: block;
+  border-radius: 0.1rem;
+  box-shadow: 0 16px 38px rgba(15, 23, 42, 0.18);
+}
+
+.image-canvas-editor__layer img {
+  pointer-events: none;
+}
+
+.image-canvas-editor__layer-video-preview {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  display: block;
+  border-radius: 0.1rem;
+  box-shadow: 0 16px 38px rgba(15, 23, 42, 0.18);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 180ms ease;
+}
+
+.image-canvas-editor__layer-video-preview--visible {
+  opacity: 1;
+}
+
+.image-canvas-editor__layer-video {
+  position: relative;
+  z-index: 1;
+}
+
+.image-canvas-editor__audio-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+  justify-content: flex-end;
+  gap: 0.3rem;
+  border-radius: 0.85rem;
+  background: linear-gradient(135deg, #0f172a, #263449);
+  padding: 0.7rem;
+  box-shadow: 0 16px 38px rgba(15, 23, 42, 0.18);
+}
+
+.image-canvas-editor__audio-card-playback {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  border: 0;
+  background: transparent;
+  color: rgba(255, 255, 255, 0.9);
+  cursor: pointer;
+}
+
+.image-canvas-editor__audio-card-playback:hover {
+  background: rgba(15, 23, 42, 0.18);
+}
+
+.image-canvas-editor__audio-card-title {
+  position: absolute;
+  left: 0.7rem;
+  top: 0.7rem;
+  z-index: 2;
+  overflow: hidden;
+  max-width: min(70%, calc(100% - 1.4rem));
+  color: #ffffff;
+  font-size: 0.74rem;
+  font-weight: 800;
+  line-height: 1.1;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-shadow: 0 1px 6px rgba(15, 23, 42, 0.55);
+}
+
+.image-canvas-editor__audio-card-controls {
+  position: relative;
+  z-index: 2;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto auto minmax(2rem, 3.8rem);
+  align-items: center;
+  gap: 0.34rem;
+  min-height: 1.85rem;
+  padding: 0.18rem 0;
+  color: rgba(255, 255, 255, 0.92);
+  transform: translateY(calc(100% + 0.7rem));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform 180ms ease,
+    opacity 180ms ease;
+}
+
+.image-canvas-editor__audio-card--controls-visible
+  .image-canvas-editor__audio-card-controls {
+  transform: translateY(0);
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.image-canvas-editor__audio-card audio {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.image-canvas-editor__audio-card-time {
+  min-width: 2.2rem;
+  font-size: 0.58rem;
+  font-weight: 800;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  text-align: center;
+  text-shadow: 0 1px 4px rgba(15, 23, 42, 0.42);
+}
+
+.image-canvas-editor__audio-card-progress,
+.image-canvas-editor__audio-card-volume {
+  min-width: 0;
+  height: 0.35rem;
+  accent-color: #67e8f9;
+  cursor: pointer;
+}
+
+.image-canvas-editor__audio-card-progress:disabled {
+  cursor: default;
+  opacity: 0.45;
+}
+
+.image-canvas-editor__audio-card-volume-toggle {
+  display: grid;
+  width: 1.25rem;
+  height: 1.25rem;
+  place-items: center;
+  border: 0;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.14);
+  color: #ffffff;
+  cursor: pointer;
+}
+
+.image-canvas-editor__audio-card-volume-toggle:hover {
+  background: rgba(255, 255, 255, 0.24);
+}
+
+.image-canvas-editor__layer--hovered,
+.image-canvas-editor__layer--selected {
+  border-color: #4bb5aa;
+}
+
+.image-canvas-editor__layer--selected {
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.9);
+}
+
+.image-canvas-editor__layer--locked {
+  cursor: not-allowed;
+}
+
+.image-canvas-editor__layer--locked::after {
+  content: '';
+  position: absolute;
+  inset: -0.28rem;
+  border: 1px dashed rgba(71, 85, 105, 0.55);
+  border-radius: 0.32rem;
+  pointer-events: none;
+}
+
+.image-canvas-editor__layer--generating {
+  cursor: progress;
+}
+
+.image-canvas-editor__layer--generating::before {
+  content: '';
+  position: absolute;
+  z-index: 2;
+  inset: 0;
+  overflow: hidden;
+  border-radius: 0.1rem;
+  background: linear-gradient(
+      90deg,
+      transparent,
+      rgba(255, 255, 255, 0.52),
+      transparent
+    ),
+    rgba(248, 250, 252, 0.32);
+  animation: image-canvas-generation-scan 1.7s linear infinite;
+  pointer-events: none;
+}
+
+.image-canvas-editor__layer-generating-progress {
+  z-index: 3;
+  bottom: 0.7rem;
+}
+
+.image-canvas-editor__generation-frame {
+  position: absolute;
+  z-index: 6;
+  display: grid;
+  place-items: center;
+  border: 2px solid transparent;
+  background: #eeeeee;
+  color: #9ca3af;
+  cursor: move;
+  box-shadow: 0 16px 38px rgba(15, 23, 42, 0.08);
+}
+
+.image-canvas-editor__generation-frame--focused {
+  border-color: #2f7df6;
+}
+
+.image-canvas-editor__generation-frame-label,
+.image-canvas-editor__generation-frame-size {
+  position: absolute;
+  top: var(--image-canvas-editor-frame-label-offset, -1.35rem);
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  color: #2f7df6;
+  font-size: 0.76rem;
+  font-weight: 850;
+  line-height: 1;
+  white-space: nowrap;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+}
+
+.image-canvas-editor__generation-frame-label {
+  left: 0;
+  transform-origin: bottom left;
+}
+
+.image-canvas-editor__generation-frame-size {
+  right: 0;
+  transform-origin: bottom right;
+}
+
+.image-canvas-editor__generation-frame-icon {
+  display: grid;
+  place-items: center;
+  color: #c7c7c7;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+  transform-origin: center;
+}
+
+.image-canvas-editor__generation-frame--character {
+  background: radial-gradient(
+      circle at 50% 34%,
+      rgba(250, 245, 255, 0.94),
+      transparent 30%
+    ),
+    linear-gradient(135deg, rgba(250, 245, 255, 0.84), rgba(243, 232, 255, 0.72));
+}
+
+.image-canvas-editor__generation-frame--character.image-canvas-editor__generation-frame--focused {
+  border-color: rgba(147, 51, 234, 0.72);
+}
+
+.image-canvas-editor__generation-frame--character
+  .image-canvas-editor__generation-frame-icon {
+  color: #9333ea;
+}
+
+.image-canvas-editor__generation-frame--character-animation {
+  background:
+    radial-gradient(circle at 50% 36%, rgba(255, 247, 237, 0.96), transparent 32%),
+    linear-gradient(135deg, rgba(255, 247, 237, 0.92), rgba(254, 215, 170, 0.74));
+}
+
+.image-canvas-editor__generation-frame--character-animation.image-canvas-editor__generation-frame--focused {
+  border-color: rgba(249, 115, 22, 0.74);
+}
+
+.image-canvas-editor__generation-frame--character-animation
+  .image-canvas-editor__generation-frame-icon {
+  color: #f97316;
+}
+
+.image-canvas-editor__generation-frame--video {
+  background:
+    linear-gradient(90deg, rgba(15, 23, 42, 0.12) 10%, transparent 10% 90%, rgba(15, 23, 42, 0.12) 90%),
+    linear-gradient(135deg, rgba(239, 246, 255, 0.9), rgba(219, 234, 254, 0.82));
+}
+
+.image-canvas-editor__generation-frame--video.image-canvas-editor__generation-frame--focused {
+  border-color: rgba(37, 99, 235, 0.72);
+}
+
+.image-canvas-editor__generation-frame--video
+  .image-canvas-editor__generation-frame-icon {
+  color: #2563eb;
+}
+
+.image-canvas-editor__generation-frame--audio-sound-effect,
+.image-canvas-editor__generation-frame--audio-background-music {
+  background:
+    repeating-linear-gradient(
+      90deg,
+      rgba(79, 70, 229, 0.14) 0 0.22rem,
+      transparent 0.22rem 0.58rem
+    ),
+    linear-gradient(135deg, rgba(238, 242, 255, 0.92), rgba(224, 231, 255, 0.8));
+}
+
+.image-canvas-editor__generation-frame--audio-sound-effect.image-canvas-editor__generation-frame--focused,
+.image-canvas-editor__generation-frame--audio-background-music.image-canvas-editor__generation-frame--focused {
+  border-color: rgba(79, 70, 229, 0.72);
+}
+
+.image-canvas-editor__generation-frame--audio-sound-effect
+  .image-canvas-editor__generation-frame-icon,
+.image-canvas-editor__generation-frame--audio-background-music
+  .image-canvas-editor__generation-frame-icon {
+  color: #4f46e5;
+}
+
+.image-canvas-editor__generation-frame--generating {
+  overflow: hidden;
+  background: radial-gradient(
+      circle at 50% 38%,
+      rgba(255, 255, 255, 0.96),
+      transparent 34%
+    ),
+    linear-gradient(
+      135deg,
+      rgba(240, 247, 255, 0.92),
+      rgba(232, 236, 244, 0.95)
+    );
+  color: #2563eb;
+  cursor: progress;
+  box-shadow:
+    0 20px 48px rgba(15, 23, 42, 0.12),
+    inset 0 0 0 1px rgba(255, 255, 255, 0.72);
+}
+
+.image-canvas-editor__generation-frame--generating::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+      90deg,
+      transparent,
+      rgba(255, 255, 255, 0.62),
+      transparent
+    ),
+    repeating-linear-gradient(
+      135deg,
+      rgba(47, 125, 246, 0.08) 0 0.4rem,
+      transparent 0.4rem 0.85rem
+    );
+  animation: image-canvas-generation-scan 1.7s linear infinite;
+}
+
+.image-canvas-editor__generation-frame--generating
+  .image-canvas-editor__generation-frame-label,
+.image-canvas-editor__generation-frame--generating
+  .image-canvas-editor__generation-frame-size {
+  color: #2563eb;
+}
+
+.image-canvas-editor__generation-frame--generating
+  .image-canvas-editor__generation-frame-icon {
+  position: relative;
+  z-index: 1;
+  width: 5.5rem;
+  aspect-ratio: 1;
+  border: 1px solid rgba(37, 99, 235, 0.18);
+  border-radius: 1.6rem;
+  background: rgba(255, 255, 255, 0.78);
+  color: rgba(37, 99, 235, 0.58);
+  box-shadow: 0 18px 32px rgba(37, 99, 235, 0.12);
+}
+
+.image-canvas-editor__generation-frame-progress {
+  position: absolute;
+  left: 50%;
+  bottom: 1rem;
+  z-index: 2;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  border: 1px solid rgba(37, 99, 235, 0.18);
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.86);
+  padding: 0.34rem 0.7rem;
+  color: #1d4ed8;
+  font-size: 0.76rem;
+  font-weight: 850;
+  transform: translateX(-50%);
+  box-shadow: 0 12px 24px rgba(37, 99, 235, 0.12);
+}
+
+.image-canvas-editor__generation-frame-progress::before {
+  content: '';
+  width: 0.45rem;
+  height: 0.45rem;
+  border-radius: 999px;
+  background: currentColor;
+  animation: image-canvas-generation-pulse 1s ease-in-out infinite;
+}
+
+@keyframes image-canvas-generation-scan {
+  from {
+    transform: translateX(-65%);
+  }
+  to {
+    transform: translateX(65%);
+  }
+}
+
+@keyframes image-canvas-generation-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+    transform: scale(0.82);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1.08);
+  }
+}
+
+.image-canvas-editor__generation-frame--icon {
+  background: linear-gradient(
+      135deg,
+      rgba(255, 255, 255, 0.72),
+      rgba(236, 253, 245, 0.86)
+    ),
+    #ecfdf5;
+}
+
+.image-canvas-editor__generation-frame--icon.image-canvas-editor__generation-frame--focused {
+  border-color: #10b981;
+}
+
+.image-canvas-editor__generation-frame--icon::before,
+.image-canvas-editor__generation-frame--icon::after {
+  content: '';
+  position: absolute;
+  width: 42%;
+  aspect-ratio: 1;
+  border: 2px solid rgba(16, 185, 129, 0.32);
+  border-radius: 1.15rem;
+  background: rgba(255, 255, 255, 0.82);
+  box-shadow: 0 12px 24px rgba(15, 118, 110, 0.12);
+}
+
+.image-canvas-editor__generation-frame--icon::before {
+  transform: translate(-20%, -8%) rotate(-8deg);
+}
+
+.image-canvas-editor__generation-frame--icon::after {
+  transform: translate(18%, 10%) rotate(7deg);
+}
+
+.image-canvas-editor__generation-frame--icon
+  .image-canvas-editor__generation-frame-icon {
+  position: relative;
+  z-index: 1;
+  width: 28%;
+  aspect-ratio: 1;
+  border: 2px solid rgba(16, 185, 129, 0.42);
+  border-radius: 1.1rem;
+  background: rgba(255, 255, 255, 0.92);
+  color: #10b981;
+  box-shadow: 0 16px 28px rgba(16, 185, 129, 0.16);
+}
+
+.image-canvas-editor__generation-frame--ui-design {
+  background: linear-gradient(
+      90deg,
+      rgba(245, 158, 11, 0.12) 1px,
+      transparent 1px
+    ),
+    linear-gradient(0deg, rgba(245, 158, 11, 0.1) 1px, transparent 1px),
+    rgba(255, 251, 235, 0.82);
+  background-size: 42px 42px;
+}
+
+.image-canvas-editor__generation-frame--ui-design.image-canvas-editor__generation-frame--focused {
+  border-color: rgba(245, 158, 11, 0.72);
+}
+
+.image-canvas-editor__generation-frame--ui-design
+  .image-canvas-editor__generation-frame-icon {
+  color: #d97706;
+}
+
+.image-canvas-editor__generation-frame--quick-edit {
+  border-color: rgba(99, 102, 241, 0.28);
+  background:
+    linear-gradient(135deg, rgba(99, 102, 241, 0.12), rgba(14, 165, 233, 0.08)),
+    rgba(255, 255, 255, 0.72);
+}
+
+.image-canvas-editor__generation-frame--quick-edit.image-canvas-editor__generation-frame--focused {
+  box-shadow:
+    0 0 0 1px rgba(99, 102, 241, 0.26),
+    0 22px 54px rgba(99, 102, 241, 0.18);
+}
+
+.image-canvas-editor__generation-frame--quick-edit
+  .image-canvas-editor__generation-frame-icon {
+  color: rgba(79, 70, 229, 0.62);
+}
+
+.image-canvas-editor__generation-frame--publication {
+  border-color: rgba(236, 72, 153, 0.28);
+  background:
+    radial-gradient(circle at 30% 20%, rgba(244, 114, 182, 0.18), transparent 38%),
+    linear-gradient(135deg, rgba(236, 72, 153, 0.12), rgba(251, 146, 60, 0.08)),
+    rgba(255, 247, 252, 0.78);
+}
+
+.image-canvas-editor__generation-frame--publication.image-canvas-editor__generation-frame--focused {
+  box-shadow:
+    0 0 0 1px rgba(236, 72, 153, 0.28),
+    0 22px 54px rgba(236, 72, 153, 0.18);
+}
+
+.image-canvas-editor__generation-frame--publication
+  .image-canvas-editor__generation-frame-icon {
+  color: rgba(219, 39, 119, 0.64);
+}
+
+.image-canvas-editor__metadata-corner {
+  position: absolute;
+  right: var(--image-canvas-editor-corner-offset, 0.35rem);
+  top: var(--image-canvas-editor-corner-offset, 0.35rem);
+  z-index: 2;
+  display: grid;
+  width: 1.35rem;
+  height: 1.35rem;
+  place-items: center;
+  border-radius: 999px;
+  background: rgba(16, 15, 14, 0.78);
+  color: #ffffff;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+  transform-origin: top right;
+}
+
+.image-canvas-editor__metadata-corner:hover {
+  background: rgba(3, 105, 161, 0.88);
+}
+
+.image-canvas-editor__metadata-corner--beside-spec {
+  right: var(--image-canvas-editor-beside-kind-offset, 1.95rem);
+}
+
+.image-canvas-editor__metadata-corner--beside-kind {
+  right: var(--image-canvas-editor-corner-offset, 0.35rem);
+}
+
+.image-canvas-editor__spec-badge {
+  position: absolute;
+  right: 0.38rem;
+  top: 0.38rem;
+  z-index: 3;
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid rgba(255, 255, 255, 0.72);
+  border-radius: 999px;
+  background: rgba(37, 99, 235, 0.9);
+  padding: 0.22rem 0.5rem;
+  color: #ffffff;
+  font-size: 0.72rem;
+  font-weight: 900;
+  line-height: 1;
+  letter-spacing: 0.04em;
+  box-shadow: 0 8px 18px rgba(37, 99, 235, 0.24);
+  pointer-events: none;
+}
+
+.image-canvas-editor__kind-badge {
+  position: absolute;
+  right: var(--image-canvas-editor-kind-offset, 0.38rem);
+  top: var(--image-canvas-editor-kind-offset, 0.38rem);
+  z-index: 3;
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid rgba(255, 255, 255, 0.72);
+  border-radius: 999px;
+  padding: 0.22rem 0.5rem;
+  color: #ffffff;
+  font-size: 0.72rem;
+  font-weight: 900;
+  line-height: 1;
+  letter-spacing: 0.04em;
+  pointer-events: none;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+  transform-origin: top right;
+}
+
+.image-canvas-editor__kind-badge--editable {
+  border: 1px solid rgba(255, 255, 255, 0.72);
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.image-canvas-editor__kind-badge--beside-info {
+  right: var(--image-canvas-editor-beside-kind-offset, 1.95rem);
+}
+
+.image-canvas-editor__kind-badge--spec {
+  background: rgba(37, 99, 235, 0.9);
+  box-shadow: 0 8px 18px rgba(37, 99, 235, 0.24);
+}
+
+.image-canvas-editor__kind-badge--character {
+  background: rgba(147, 51, 234, 0.92);
+  box-shadow: 0 8px 18px rgba(147, 51, 234, 0.24);
+}
+
+.image-canvas-editor__kind-badge--character-animation {
+  background: rgba(249, 115, 22, 0.94);
+  box-shadow: 0 8px 18px rgba(249, 115, 22, 0.24);
+}
+
+.image-canvas-editor__kind-badge--icon {
+  background: rgba(16, 185, 129, 0.92);
+  box-shadow: 0 8px 18px rgba(16, 185, 129, 0.24);
+}
+
+.image-canvas-editor__kind-badge--icon-spritesheet {
+  background: rgba(20, 184, 166, 0.92);
+  box-shadow: 0 8px 18px rgba(20, 184, 166, 0.24);
+}
+
+.image-canvas-editor__kind-badge--icon-spec {
+  background: rgba(13, 148, 136, 0.92);
+  box-shadow: 0 8px 18px rgba(13, 148, 136, 0.24);
+}
+
+.image-canvas-editor__kind-badge--ui-design {
+  background: rgba(245, 158, 11, 0.94);
+  box-shadow: 0 8px 18px rgba(245, 158, 11, 0.24);
+}
+
+.image-canvas-editor__kind-badge--publication {
+  background: rgba(219, 39, 119, 0.92);
+  box-shadow: 0 8px 18px rgba(219, 39, 119, 0.24);
+}
+
+.image-canvas-editor__kind-badge--publication-material {
+  background: rgba(219, 39, 119, 0.92);
+  box-shadow: 0 8px 18px rgba(219, 39, 119, 0.24);
+}
+
+.image-canvas-editor__kind-badge--unknown {
+  background: rgba(71, 85, 105, 0.88);
+  box-shadow: 0 8px 18px rgba(71, 85, 105, 0.2);
+}
+
+.image-canvas-editor__kind-badge--video {
+  background: rgba(37, 99, 235, 0.92);
+  box-shadow: 0 8px 18px rgba(37, 99, 235, 0.24);
+}
+
+.image-canvas-editor__kind-badge--sound-effect,
+.image-canvas-editor__kind-badge--background-music {
+  background: rgba(79, 70, 229, 0.92);
+  box-shadow: 0 8px 18px rgba(79, 70, 229, 0.24);
+}
+
+.image-canvas-editor__kind-menu-anchor {
+  position: absolute;
+  width: 0;
+  height: 0;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+  transform-origin: top right;
+}
+
+.image-canvas-editor__kind-menu {
+  max-height: 16rem;
+  overflow-y: auto;
+}
+
+.image-canvas-editor__kind-menu-item--active {
+  background: #eff6ff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__size-badge {
+  position: absolute;
+  left: var(--image-canvas-editor-corner-offset, 0.35rem);
+  top: var(--image-canvas-editor-corner-offset, 0.35rem);
+  z-index: 2;
+  border-color: rgba(255, 255, 255, 0.16);
+  background: rgba(16, 15, 14, 0.82);
+  color: #ffffff;
+  white-space: nowrap;
+  transform: scale(var(--image-canvas-editor-inverse-scale, 1));
+  transform-origin: top left;
+}
+
+.image-canvas-editor__floating-toolbar {
+  position: absolute;
+  z-index: 8;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  border: 1px solid #d9dee8;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  padding: 0.28rem;
+  box-shadow: 0 18px 34px rgba(15, 23, 42, 0.18);
+  transform: translate(-50%, -100%);
+}
+
+.image-canvas-editor__floating-toolbar button.image-canvas-editor__floating-toolbar-text-button {
+  width: auto;
+  min-width: 0;
+  gap: 0.35rem;
+  padding: 0 0.62rem;
+  font-size: 0.74rem;
+  font-weight: 850;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__reset-button {
+  position: absolute;
+  right: 0.85rem;
+  bottom: 0.85rem;
+  z-index: 9;
+}
+
+.image-canvas-editor__minimap {
+  position: absolute;
+  left: 0.85rem;
+  bottom: 4rem;
+  z-index: 10;
+  display: block;
+  width: 8.25rem;
+  height: 5.25rem;
+  overflow: hidden;
+  border: 1px solid #d9dee8;
+  border-radius: 0.5rem;
+  background: rgba(255, 255, 255, 0.92);
+  padding: 0;
+  box-shadow: 0 16px 34px rgba(15, 23, 42, 0.12);
+}
+
+.image-canvas-editor__minimap-stage {
+  position: relative;
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.image-canvas-editor__minimap-layer,
+.image-canvas-editor__minimap-viewport {
+  position: absolute;
+  display: block;
+  border-radius: 0.12rem;
+}
+
+.image-canvas-editor__minimap-layer {
+  background: #d9dde3;
+}
+
+.image-canvas-editor__minimap-layer:nth-child(even) {
+  background: #eceff3;
+}
+
+.image-canvas-editor__minimap-viewport {
+  border: 1.5px solid #aeb7c5;
+  background: rgba(255, 255, 255, 0.2);
+}
+
+.image-canvas-editor__panel-dock {
+  position: absolute;
+  left: 0.85rem;
+  bottom: 0.85rem;
+  z-index: 18;
+  display: inline-flex;
+  gap: 0.35rem;
+  border: 1px solid #d9dee8;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  padding: 0.35rem;
+  box-shadow: 0 16px 34px rgba(15, 23, 42, 0.14);
+}
+
+.image-canvas-editor__panel-dock button {
+  display: inline-flex;
+  width: 2.25rem;
+  height: 2.25rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid #d9dee8;
+  border-radius: 0.45rem;
+  background: #ffffff;
+  color: #334155;
+  transition:
+    transform 160ms ease,
+    background-color 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease;
+}
+
+.image-canvas-editor__background-control {
+  position: relative;
+  display: inline-flex;
+}
+
+.image-canvas-editor__background-swatch-current,
+.image-canvas-editor__background-swatch {
+  display: block;
+  border: 1px solid #94a3b8;
+  border-radius: 999px;
+}
+
+.image-canvas-editor__background-swatch-current {
+  width: 0.9rem;
+  height: 0.9rem;
+}
+
+.image-canvas-editor__background-swatch {
+  width: 1rem;
+  height: 1rem;
+}
+
+.image-canvas-editor__background-panel {
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 0.55rem);
+  z-index: 24;
+  display: grid;
+  width: min(17.5rem, calc(100vw - 1.5rem));
+  gap: 0.62rem;
+  border: 1px solid rgba(203, 213, 225, 0.72);
+  border-radius: 0.92rem;
+  background: #ffffff;
+  padding: 0.75rem;
+  color: #1f2937;
+  box-shadow: 0 18px 42px rgba(15, 23, 42, 0.15);
+}
+
+.image-canvas-editor__background-panel-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding-bottom: 0.15rem;
+  font-size: 0.82rem;
+  font-weight: 880;
+}
+
+.image-canvas-editor__background-current-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-height: 2rem;
+  border: 1px solid #e2e8f0;
+  border-radius: 0.6rem;
+  background: #f8fafc;
+  padding: 0.35rem 0.45rem;
+  color: #475569;
+  font-size: 0.74rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__background-current-preview {
+  width: 1.24rem;
+  height: 1.24rem;
+  flex: 0 0 auto;
+  border: 1px solid #cbd5e1;
+  border-radius: 0.36rem;
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.72);
+}
+
+.image-canvas-editor__background-close {
+  display: inline-flex;
+  width: 1.65rem;
+  height: 1.65rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid transparent;
+  border-radius: 0.42rem;
+  background: transparent;
+  color: #334155;
+}
+
+.image-canvas-editor__panel-dock .image-canvas-editor__background-panel button {
+  width: auto;
+  height: auto;
+}
+
+.image-canvas-editor__background-close:hover {
+  border-color: #d7dfe9;
+  background: #f8fafc;
+}
+
+.image-canvas-editor__background-spectrum {
+  position: relative;
+  display: block;
+  height: 7.6rem;
+  overflow: hidden;
+  border: 1px solid #e2e8f0;
+  border-radius: 0.58rem;
+  background: linear-gradient(to top, #000000, transparent),
+    linear-gradient(to right, #ffffff, transparent), #ef4444;
+}
+
+.image-canvas-editor__background-spectrum input,
+.image-canvas-editor__background-hue input {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  cursor: pointer;
+  opacity: 0;
+}
+
+.image-canvas-editor__background-spectrum-surface {
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(to top, #000000, transparent),
+    linear-gradient(to right, #ffffff, transparent);
+  pointer-events: none;
+}
+
+.image-canvas-editor__background-spectrum-handle {
+  position: absolute;
+  top: 0.22rem;
+  left: 0.22rem;
+  width: 0.72rem;
+  height: 0.72rem;
+  border: 2px solid #ffffff;
+  border-radius: 999px;
+  box-shadow: 0 0 0 1px rgba(15, 23, 42, 0.25);
+  pointer-events: none;
+}
+
+.image-canvas-editor__background-hue {
+  position: relative;
+  display: block;
+  height: 0.78rem;
+  overflow: hidden;
+  border: 2px solid #ffffff;
+  border-radius: 999px;
+  background: linear-gradient(
+    to right,
+    #ff0000,
+    #ffff00,
+    #00ff00,
+    #00ffff,
+    #0000ff,
+    #ff00ff,
+    #ff0000
+  );
+  box-shadow: 0 0 0 1px rgba(203, 213, 225, 0.72);
+}
+
+.image-canvas-editor__background-presets {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 0.5rem;
+  padding: 0.02rem;
+}
+
+.image-canvas-editor__background-preset {
+  display: inline-flex;
+  width: 100%;
+  height: 2.15rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid #e2e8f0;
+  border-radius: 0.58rem;
+  background: #f8fafc;
+  padding: 0;
+}
+
+.image-canvas-editor__panel-dock .image-canvas-editor__background-preset {
+  width: 100%;
+  height: 2.15rem;
+}
+
+.image-canvas-editor__background-preset[aria-pressed='true'] {
+  border-color: #38bdf8;
+  background: #e0f2fe;
+}
+
+.image-canvas-editor__background-preset
+  .image-canvas-editor__background-swatch {
+  width: 1.55rem;
+  height: 1.55rem;
+  border-color: #e2e8f0;
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.7);
+}
+
+.image-canvas-editor__background-footer {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.image-canvas-editor__background-hex-field {
+  display: flex;
+  align-items: center;
+  gap: 0.45rem;
+  min-height: 1.9rem;
+  border-radius: 0.5rem;
+  background: #f4f5f7;
+  padding: 0 0.62rem;
+  color: #64748b;
+  font-size: 0.72rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__background-hex-field input {
+  min-width: 0;
+  flex: 1;
+  border: 0;
+  background: transparent;
+  color: #475569;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    'Liberation Mono', 'Courier New', monospace;
+  font-size: 0.78rem;
+  font-weight: 820;
+  outline: none;
+  text-transform: lowercase;
+}
+
+.image-canvas-editor__background-reset {
+  display: inline-flex;
+  height: 1.9rem;
+  white-space: nowrap;
+  align-items: center;
+  gap: 0.34rem;
+  border: 1px solid #d7dfe9;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  padding: 0.34rem 0.55rem;
+  color: #475569;
+  font-size: 0.72rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__background-reset:hover {
+  border-color: #38bdf8;
+  background: #eff6ff;
+  color: #0369a1;
+}
+
+.image-canvas-editor__panel-dock button:hover,
+.image-canvas-editor__panel-dock button[aria-pressed='true'] {
+  transform: translateY(-1px);
+  border-color: #38bdf8;
+  background: #e0f2fe;
+  color: #0369a1;
+}
+
+.image-canvas-editor__bottom-toolbar {
+  position: absolute;
+  left: 50%;
+  bottom: 0.85rem;
+  z-index: 18;
+  display: inline-flex;
+  gap: 0.35rem;
+  max-width: min(calc(100% - 6.6rem), 34rem);
+  overflow-x: auto;
+  border: 1px solid #d9dee8;
+  border-radius: 0.5rem;
+  background: #ffffff;
+  padding: 0.35rem;
+  box-shadow: 0 18px 38px rgba(15, 23, 42, 0.16);
+  transform: translateX(-50%);
+}
+
+.image-canvas-editor__bottom-toolbar button[aria-pressed='true'] {
+  border-color: #38bdf8;
+  background: #e0f2fe;
+  color: #0369a1;
+}
+
+.image-canvas-editor__bottom-toolbar-option-wrap,
+.image-canvas-editor__spec-tool-wrap {
+  position: relative;
+  display: inline-flex;
+}
+
+.image-canvas-editor__spec-menu {
+  min-width: 8.8rem;
+}
+
+.image-canvas-editor__portal-menu {
+  z-index: 70;
+}
+
+.image-canvas-editor__spec-menu-item {
+  font-weight: 850;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__generation-composer {
+  position: absolute;
+  z-index: 13;
+  display: grid;
+  grid-template-columns: 3.8rem minmax(0, 1fr);
+  grid-template-rows: minmax(5.9rem, auto) auto auto;
+  width: min(38rem, calc(100% - 1.5rem));
+  min-height: 10.4rem;
+  gap: 0.38rem 0.72rem;
+  border: 1px solid rgba(15, 23, 42, 0.09);
+  border-radius: 1.45rem;
+  background: rgba(255, 255, 255, 0.97);
+  padding: 0.72rem 0.82rem 0.82rem;
+  color: #1f2937;
+  font-size: 0.82rem;
+  box-shadow:
+    0 22px 60px rgba(15, 23, 42, 0.12),
+    inset 0 1px 0 rgba(255, 255, 255, 0.94);
+  transform: translateX(-50%);
+  backdrop-filter: blur(18px);
+}
+
+.image-canvas-editor__generation-composer--image {
+  grid-template-columns: 4rem minmax(0, 1fr);
+  grid-template-rows: auto auto auto;
+  width: min(42rem, calc(100% - 1.5rem));
+  gap: 0.18rem 0.72rem;
+}
+
+.image-canvas-editor__generation-composer--video {
+  grid-template-rows: auto auto auto;
+  gap: 0.18rem 0.72rem;
+}
+
+.image-canvas-editor__generation-composer--character-animation {
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: auto auto auto auto auto;
+  width: min(42rem, calc(100% - 1.5rem));
+}
+
+.image-canvas-editor__generation-ref {
+  display: flex;
+  width: auto;
+  height: auto;
+  min-width: 0;
+  align-self: start;
+  grid-column: 1 / -1;
+}
+
+.image-canvas-editor__generation-ref span {
+  margin-top: 0;
+}
+
+.image-canvas-editor__generation-prompt {
+  grid-column: 1 / -1;
+  min-height: 3.35rem;
+  resize: none;
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 1.05rem;
+  background: #f8fafc;
+  padding: 0.52rem 0.82rem;
+  color: #0f172a;
+  font: inherit;
+  font-size: 0.82rem;
+  font-weight: 680;
+  line-height: 1.48;
+  outline: none;
+}
+
+.image-canvas-editor__generation-prompt::placeholder {
+  color: #94a3b8;
+}
+
+.image-canvas-editor__generation-prompt--borderless {
+  border-color: transparent;
+  background: transparent;
+  box-shadow: none;
+}
+
+.image-canvas-editor__generation-prompt--borderless:focus {
+  border-color: transparent;
+  background: transparent;
+  box-shadow: none;
+}
+
+.image-canvas-editor__video-prompt {
+  grid-column: 1 / -1;
+  min-height: 4.1rem;
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 1.05rem;
+  background: #f8fafc;
+  padding: 0.64rem 0.9rem;
+}
+
+.image-canvas-editor__generation-composer-footer {
+  grid-column: 1 / -1;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 0.46rem;
+  position: relative;
+  border-top: 1px solid rgba(15, 23, 42, 0.06);
+  padding-top: 0.44rem;
+}
+
+.image-canvas-editor__generation-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  background: transparent;
+  color: #374151;
+  font-size: 0.82rem;
+  font-weight: 800;
+}
+
+.image-canvas-editor__generation-ratio {
+  justify-self: start;
+  gap: 0.2rem;
+}
+
+.image-canvas-editor__generation-model {
+  gap: 0.25rem;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__inline-option-group {
+  display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.28rem;
+}
+
+.image-canvas-editor__reference-strip {
+  display: flex;
+  grid-column: 1 / -1;
+  min-width: 0;
+  align-items: center;
+  gap: 0.36rem;
+  overflow-x: auto;
+  padding: 0 2.2rem 0.02rem 0;
+  scrollbar-width: thin;
+}
+
+.image-canvas-editor__reference-slot {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  width: 3.95rem;
+  height: 3.95rem;
+}
+
+.image-canvas-editor__reference-chip {
+  position: relative;
+  display: inline-grid;
+  width: 3.95rem;
+  min-width: 3.95rem;
+  max-width: 3.95rem;
+  height: 3.95rem;
+  min-height: 3.95rem;
+  grid-template-rows: 1.42rem auto;
+  align-items: center;
+  justify-items: center;
+  gap: 0.28rem;
+  overflow: hidden;
+  border: 1px solid rgba(148, 163, 184, 0.16);
+  border-radius: 1rem;
+  background: #f2f3f5;
+  padding: 0.62rem 0.36rem 0.5rem;
+  color: #a3a8ae;
+  font-size: 0.68rem;
+  font-weight: 850;
+  line-height: 1.04;
+  text-align: center;
+  box-shadow: none;
+}
+
+button.image-canvas-editor__reference-chip {
+  cursor: pointer;
+}
+
+button.image-canvas-editor__reference-chip:hover:not(:disabled) {
+  transform: translateY(-1px);
+  border-color: rgba(148, 163, 184, 0.22);
+  background: #eef0f2;
+}
+
+button.image-canvas-editor__reference-chip:disabled {
+  cursor: not-allowed;
+  opacity: 0.62;
+  transform: none;
+}
+
+.image-canvas-editor__reference-chip-icon {
+  display: grid;
+  width: 1.42rem;
+  height: 1.42rem;
+  flex: 0 0 auto;
+  place-items: center;
+  overflow: hidden;
+  border-radius: 0.36rem;
+  background: transparent;
+  color: currentColor;
+}
+
+.image-canvas-editor__reference-chip-icon img {
+  width: 100%;
+  height: 100%;
+  border-radius: 0.36rem;
+  object-fit: cover;
+}
+
+.image-canvas-editor__reference-chip-label {
+  display: -webkit-box;
+  min-width: 0;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  text-overflow: ellipsis;
+  white-space: normal;
+  word-break: keep-all;
+}
+
+.image-canvas-editor__reference-chip-source-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  clip-path: inset(50%);
+}
+
+.image-canvas-editor__reference-chip-remove {
+  position: absolute;
+  top: 0.16rem;
+  right: 0.16rem;
+  z-index: 2;
+  display: grid;
+  width: 1.12rem;
+  height: 1.12rem;
+  place-items: center;
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 999px;
+  background: rgba(15, 23, 42, 0.86);
+  color: #ffffff;
+  opacity: 0;
+  box-shadow: 0 8px 18px rgba(15, 23, 42, 0.18);
+  pointer-events: none;
+  transform: scale(0.88);
+  transition:
+    opacity 120ms ease,
+    transform 120ms ease;
+}
+
+.image-canvas-editor__reference-slot:hover
+  .image-canvas-editor__reference-chip-remove,
+.image-canvas-editor__reference-slot:focus-within
+  .image-canvas-editor__reference-chip-remove {
+  opacity: 1;
+  pointer-events: auto;
+  transform: scale(1);
+}
+
+.image-canvas-editor__reference-chip-remove:disabled {
+  cursor: not-allowed;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.image-canvas-editor__reference-chip-remove:hover:not(:disabled) {
+  background: rgba(220, 38, 38, 0.95);
+}
+
+.image-canvas-editor__reference-chip--has-image
+  .image-canvas-editor__reference-chip-icon {
+  width: 1.74rem;
+  height: 1.74rem;
+  border-radius: 0.48rem;
+}
+
+.image-canvas-editor__reference-chip--has-image
+  .image-canvas-editor__reference-chip-icon
+  img {
+  border-radius: 0.48rem;
+}
+
+.image-canvas-editor__reference-chip--spec
+  .image-canvas-editor__reference-chip-icon {
+  color: #8b5cf6;
+}
+
+.image-canvas-editor__reference-chip--icon
+  .image-canvas-editor__reference-chip-icon {
+  color: #059669;
+}
+
+.image-canvas-editor__reference-chip--ui
+  .image-canvas-editor__reference-chip-icon {
+  color: #d97706;
+}
+
+.image-canvas-editor__reference-chip--character
+  .image-canvas-editor__reference-chip-icon {
+  color: #0f172a;
+}
+
+.image-canvas-editor__reference-chip--quick-edit {
+  background: #f3f4f6;
+  color: #9ca3af;
+}
+
+.image-canvas-editor__reference-chip--quick-edit
+  .image-canvas-editor__reference-chip-icon {
+  color: #9ca3af;
+}
+
+.image-canvas-editor__reference-chip--video
+  .image-canvas-editor__reference-chip-icon {
+  color: #2563eb;
+}
+
+.image-canvas-editor__reference-chip--audio
+  .image-canvas-editor__reference-chip-icon {
+  color: #7c3aed;
+}
+
+.image-canvas-editor__option-picker {
+  width: 100%;
+  min-height: 2rem;
+  justify-content: space-between;
+  border: 1px solid transparent;
+  border-radius: 0.85rem;
+  background: transparent;
+  padding: 0 0.6rem;
+  color: #0f172a;
+  box-shadow: none;
+}
+
+.image-canvas-editor__option-cluster {
+  min-height: 2.25rem;
+  height: 2.25rem;
+  width: 100%;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  background: transparent;
+  padding: 0 0.72rem;
+  color: #0f172a;
+  box-shadow: none;
+}
+
+.image-canvas-editor__option-cluster:hover:not(:disabled),
+.image-canvas-editor__option-cluster[aria-expanded='true'] {
+  border-color: rgba(15, 23, 42, 0.08);
+  background: #f8fafc;
+  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.08);
+}
+
+.image-canvas-editor__option-cluster .platform-inline-option-button__trailing {
+  transition: transform 160ms ease;
+}
+
+.image-canvas-editor__option-cluster[aria-expanded='true']
+  .platform-inline-option-button__trailing {
+  transform: rotate(180deg);
+}
+
+.image-canvas-editor__option-cluster--dimensions {
+  grid-column: auto;
+  justify-self: start;
+  gap: 0.42rem;
+}
+
+.image-canvas-editor__option-cluster--dimensions span {
+  font-variant-numeric: tabular-nums;
+}
+
+.image-canvas-editor__option-cluster--model {
+  max-width: min(15.5rem, 32vw);
+  justify-self: end;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__option-popover-anchor {
+  position: relative;
+  min-width: 0;
+}
+
+.image-canvas-editor__option-popover-anchor--dimensions {
+  grid-column: 1;
+  justify-self: start;
+}
+
+.image-canvas-editor__option-popover-anchor--model {
+  grid-column: 3;
+  justify-self: end;
+}
+
+.image-canvas-editor__model-trigger-label {
+  display: inline-flex;
+  min-width: 0;
+  max-width: 100%;
+  align-items: center;
+  gap: 0.32rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__model-trigger-label svg,
+.image-canvas-editor__model-icon svg {
+  width: 0.88rem;
+  height: 0.88rem;
+}
+
+.image-canvas-editor__model-trigger-label span:last-child {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__model-icon {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  color: #334155;
+}
+
+.image-canvas-editor__option-popover {
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 0.45rem);
+  z-index: 3;
+  min-width: 16rem;
+  max-width: min(23rem, calc(100vw - 1.5rem));
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 1.05rem;
+  background: rgba(255, 255, 255, 0.98);
+  padding: 1.78rem 0.95rem 0.95rem;
+  color: #111827;
+  font-size: 0.82rem;
+  box-shadow:
+    0 22px 56px rgba(15, 23, 42, 0.15),
+    inset 0 1px 0 rgba(255, 255, 255, 0.96);
+  backdrop-filter: blur(16px);
+}
+
+.image-canvas-editor__option-popover-anchor--model
+  .image-canvas-editor__option-popover {
+  right: 0;
+  left: auto;
+}
+
+.image-canvas-editor__option-popover-close {
+  position: absolute;
+  right: 0.54rem;
+  top: 0.5rem;
+  display: inline-flex;
+  width: 1.35rem;
+  height: 1.35rem;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: #64748b;
+}
+
+.image-canvas-editor__option-popover-close:hover {
+  background: #f1f5f9;
+  color: #0f172a;
+}
+
+.image-canvas-editor__option-popover-sections {
+  display: grid;
+  gap: 1rem;
+}
+
+.image-canvas-editor__option-popover-section {
+  display: grid;
+  gap: 0.58rem;
+}
+
+.image-canvas-editor__option-popover-title {
+  color: #2f2f35;
+  font-size: 0.82rem;
+  font-weight: 760;
+}
+
+.image-canvas-editor__option-popover-items {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.46rem;
+}
+
+.image-canvas-editor__option-popover-items--card {
+  gap: 0.62rem;
+}
+
+.image-canvas-editor__option-popover:has(
+    .image-canvas-editor__option-popover-choice--model
+  ) {
+  min-width: 13.5rem;
+}
+
+.image-canvas-editor__option-popover-choice {
+  display: inline-flex;
+  min-width: 4.5rem;
+  min-height: 2.25rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid rgba(15, 23, 42, 0.1);
+  border-radius: 999px;
+  background: #ffffff;
+  padding: 0 0.85rem;
+  color: #111827;
+  font-size: 0.82rem;
+  font-weight: 720;
+}
+
+.image-canvas-editor__option-popover-items--card
+  .image-canvas-editor__option-popover-choice {
+  min-width: 5.25rem;
+  min-height: 4.6rem;
+  border-radius: 1rem;
+  font-size: 0.82rem;
+}
+
+.image-canvas-editor__option-popover-choice[aria-pressed='true'] {
+  border-color: #202124;
+  box-shadow: inset 0 0 0 1px #202124;
+}
+
+.image-canvas-editor__option-popover--audio-options {
+  display: grid;
+  min-width: 16.4rem;
+  gap: 0.72rem;
+  padding: 0.88rem;
+}
+
+.image-canvas-editor__audio-type-options {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.image-canvas-editor__audio-bpm-control {
+  display: grid;
+  grid-template-columns: minmax(7rem, 1fr) 4.7rem;
+  align-items: center;
+  gap: 0.56rem;
+}
+
+.image-canvas-editor__audio-bpm-control input[type='range'] {
+  width: 100%;
+  accent-color: #4f46e5;
+}
+
+.image-canvas-editor__video-duration-slider {
+  display: grid;
+  grid-template-columns: minmax(7rem, 1fr) 3.6rem;
+  align-items: center;
+  gap: 0.56rem;
+}
+
+.image-canvas-editor__video-duration-slider input[type='range'] {
+  width: 100%;
+  accent-color: #111827;
+}
+
+.image-canvas-editor__video-duration-slider span {
+  color: #111827;
+  font-size: 0.82rem;
+  font-weight: 760;
+  text-align: right;
+}
+
+.image-canvas-editor__video-toggle-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.46rem;
+}
+
+.image-canvas-editor__video-toggle {
+  display: inline-flex;
+  min-height: 2.25rem;
+  align-items: center;
+  gap: 0.48rem;
+  border: 1px solid rgba(15, 23, 42, 0.1);
+  border-radius: 999px;
+  background: #ffffff;
+  padding: 0 0.78rem;
+  color: #111827;
+  font-size: 0.82rem;
+  font-weight: 760;
+}
+
+.image-canvas-editor__video-toggle span {
+  position: relative;
+  width: 1.7rem;
+  height: 0.96rem;
+  border-radius: 999px;
+  background: #cbd5e1;
+}
+
+.image-canvas-editor__video-toggle span::after {
+  position: absolute;
+  top: 0.16rem;
+  left: 0.16rem;
+  width: 0.64rem;
+  height: 0.64rem;
+  border-radius: 999px;
+  background: #ffffff;
+  content: '';
+  transition: transform 0.16s ease;
+}
+
+.image-canvas-editor__video-toggle[aria-pressed='true'] {
+  border-color: #202124;
+  box-shadow: inset 0 0 0 1px #202124;
+}
+
+.image-canvas-editor__video-toggle[aria-pressed='true'] span {
+  background: #111827;
+}
+
+.image-canvas-editor__video-toggle[aria-pressed='true'] span::after {
+  transform: translateX(0.74rem);
+}
+
+.image-canvas-editor__audio-bpm-control input[type='number'] {
+  min-width: 0;
+  border: 1px solid rgba(15, 23, 42, 0.1);
+  border-radius: 999px;
+  background: #f8fafc;
+  padding: 0.46rem 0.62rem;
+  color: #0f172a;
+  font-size: 0.82rem;
+  font-weight: 760;
+  outline: none;
+}
+
+.image-canvas-editor__audio-bpm-control input[type='number']:focus {
+  border-color: rgba(79, 70, 229, 0.42);
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
+}
+
+.image-canvas-editor__option-popover-choice--model {
+  display: grid;
+  width: 100%;
+  grid-template-columns: 1rem minmax(0, 1fr) 1rem;
+  justify-content: stretch;
+  column-gap: 0.44rem;
+  border-color: transparent;
+  background: transparent;
+  padding: 0.18rem 0.2rem;
+  text-align: left;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__option-popover-choice--model span:nth-child(2) {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__option-popover-choice--model
+  .image-canvas-editor__model-icon {
+  justify-self: start;
+}
+
+.image-canvas-editor__option-popover-choice--model[aria-pressed='true'] {
+  border-color: transparent;
+  box-shadow: none;
+}
+
+.image-canvas-editor__option-popover-choice--model:hover {
+  background: #f8fafc;
+}
+
+.image-canvas-editor__option-selected-check {
+  width: 0.92rem;
+  height: 0.92rem;
+  justify-self: end;
+  color: #111827;
+  stroke-width: 3;
+}
+
+.image-canvas-editor__option-selected-check[data-visible='false'] {
+  opacity: 0;
+}
+
+.image-canvas-editor__option-popover-choice--ratio {
+  flex-direction: column;
+  gap: 0.42rem;
+}
+
+.image-canvas-editor__ratio-wireframe {
+  display: block;
+  width: 1.65rem;
+  height: 1.08rem;
+  border: 2px solid currentColor;
+  border-radius: 0.24rem;
+}
+
+.image-canvas-editor__ratio-wireframe[data-ratio='9:16'] {
+  width: 1.02rem;
+  height: 1.74rem;
+}
+
+.image-canvas-editor__ratio-wireframe[data-ratio='3:4'],
+.image-canvas-editor__ratio-wireframe[data-ratio='2:3'] {
+  width: 1.12rem;
+  height: 1.58rem;
+}
+
+.image-canvas-editor__ratio-wireframe[data-ratio='4:3'],
+.image-canvas-editor__ratio-wireframe[data-ratio='3:2'] {
+  width: 1.74rem;
+  height: 1.16rem;
+}
+
+.image-canvas-editor__ratio-wireframe[data-ratio='1:1'] {
+  width: 1.36rem;
+  height: 1.36rem;
+}
+
+.image-canvas-editor__mud-point-inline {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.18rem;
+  color: currentColor;
+  font-size: 0.74rem;
+  font-weight: 850;
+  line-height: 1;
+}
+
+.image-canvas-editor__mud-point-inline svg {
+  width: 0.88rem;
+  height: 0.88rem;
+}
+
+.image-canvas-editor__generation-composer .image-canvas-editor__option-field {
+  min-width: 0;
+}
+
+.image-canvas-editor__generation-composer .image-canvas-editor__field-title {
+  color: #94a3b8;
+  font-size: 0.66rem;
+  font-weight: 760;
+  letter-spacing: 0.06em;
+}
+
+.image-canvas-editor__generation-composer .platform-inline-option-button {
+  min-height: 2.25rem;
+  border-color: transparent;
+  background: transparent;
+  color: #475569;
+  font-size: 0.82rem;
+  font-weight: 760;
+  box-shadow: none;
+}
+
+.image-canvas-editor__generation-composer
+  .platform-inline-option-button[aria-pressed='true'] {
+  border-color: rgba(15, 23, 42, 0.14);
+  background: #0f172a;
+  color: #ffffff;
+}
+
+.image-canvas-editor__generation-submit {
+  grid-column: 4;
+  min-width: 5.45rem;
+  height: 2.25rem;
+  gap: 0.4rem;
+  border: 0;
+  background: #0f172a;
+  color: #ffffff;
+  font-size: 0.82rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__generation-submit:not(:disabled) {
+  color: #ffffff;
+}
+
+.image-canvas-editor__generation-submit:disabled {
+  cursor: wait;
+  background: #e2e8f0;
+  color: #94a3b8;
+}
+
+.image-canvas-editor__generation-close {
+  position: absolute;
+  right: 0.62rem;
+  top: 0.58rem;
+  width: 2rem;
+  height: 2rem;
+  color: #94a3b8;
+}
+
+.image-canvas-editor__generation-composer
+  .image-canvas-editor__generate-status {
+  grid-column: 1 / -1;
+}
+
+.image-canvas-editor__character-composer {
+  position: absolute;
+  z-index: 13;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: auto minmax(5.8rem, auto) auto auto;
+  width: min(34rem, calc(100% - 1.5rem));
+  min-height: 11.2rem;
+  gap: 0.5rem;
+  border: 1px solid #cfd6df;
+  border-radius: 1.35rem;
+  background: #ffffff;
+  padding: 0.62rem 0.7rem 0.68rem;
+  color: #1f2937;
+  box-shadow: 0 18px 46px rgba(15, 23, 42, 0.16);
+  transform: translateX(-50%);
+}
+
+.image-canvas-editor__character-composer
+  .image-canvas-editor__generation-prompt {
+  min-height: 5.8rem;
+  padding-top: 0.42rem;
+}
+
+.image-canvas-editor__character-composer
+  .image-canvas-editor__generation-composer-footer,
+.image-canvas-editor__character-composer .image-canvas-editor__generate-status {
+  grid-column: 1 / -1;
+}
+
+.image-canvas-editor__publication-composer {
+  grid-template-rows: auto auto auto;
+}
+
+.image-canvas-editor__publication-composer-fields {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 0.46rem 0.52rem;
+  min-width: 0;
+}
+
+.image-canvas-editor__publication-composer-summary,
+.image-canvas-editor__publication-description-field {
+  grid-column: 1 / -1;
+}
+
+.image-canvas-editor__publication-composer-summary {
+  display: flex;
+  min-height: 1.5rem;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+  color: #64748b;
+  font-size: 0.72rem;
+  font-weight: 780;
+}
+
+.image-canvas-editor__publication-composer-summary strong {
+  color: #111827;
+  font-size: 0.78rem;
+  font-weight: 860;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__publication-input {
+  min-height: 1.96rem;
+}
+
+.image-canvas-editor__publication-description {
+  min-height: 4rem;
+}
+
+.image-canvas-editor__publication-composer
+  .image-canvas-editor__generation-composer-footer {
+  grid-template-columns: minmax(0, 1fr) auto auto;
+}
+
+.image-canvas-editor__publication-composer
+  .image-canvas-editor__option-popover-anchor--model {
+  grid-column: 2;
+}
+
+.image-canvas-editor__publication-composer
+  .image-canvas-editor__generation-submit {
+  grid-column: 3;
+}
+
+.image-canvas-editor__icon-composer {
+  position: absolute;
+  z-index: 13;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: auto minmax(5.8rem, auto) auto auto;
+  width: min(34rem, calc(100% - 1.5rem));
+  min-height: 11.2rem;
+  gap: 0.5rem;
+  border: 1px solid #cfd6df;
+  border-radius: 1.35rem;
+  background: #ffffff;
+  padding: 0.62rem 0.7rem 0.68rem;
+  color: #1f2937;
+  box-shadow: 0 18px 46px rgba(15, 23, 42, 0.16);
+  transform: translateX(-50%);
+}
+
+.image-canvas-editor__icon-composer .image-canvas-editor__generation-prompt {
+  min-height: 5.8rem;
+  padding-top: 0.42rem;
+}
+
+.image-canvas-editor__icon-spec-card:disabled {
+  cursor: wait;
+  opacity: 0.68;
+}
+
+.image-canvas-editor__field-block {
+  display: grid;
+  gap: 0.42rem;
+  min-width: 0;
+}
+
+.image-canvas-editor__field-title {
+  margin-bottom: 0;
+}
+
+.image-canvas-editor__option-field {
+  display: grid;
+  gap: 0.3rem;
+}
+
+.image-canvas-editor__character-reference-field {
+  display: grid;
+  gap: 0.35rem;
+  min-width: 0;
+}
+
+.image-canvas-editor__character-reference-field--spec {
+  flex: 0 0 9.2rem;
+}
+
+.image-canvas-editor__character-reference-field--regular {
+  flex: 1 1 auto;
+}
+
+.image-canvas-editor__character-reference-list {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.42rem;
+  overflow-x: auto;
+  padding: 0.02rem 0 0.08rem;
+  scrollbar-width: thin;
+}
+
+.image-canvas-editor__character-reference-row {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.42rem;
+  overflow-x: auto;
+  padding: 0.02rem 2.2rem 0.08rem 0;
+  scrollbar-width: thin;
+}
+
+.image-canvas-editor__character-spec-wrap {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+}
+
+.image-canvas-editor__character-spec-ref,
+.image-canvas-editor__character-reference-add {
+  display: inline-flex;
+  min-width: 4.25rem;
+  height: 3.55rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px dashed #c7d2fe;
+  border-radius: 0.9rem;
+  background: #f8fafc;
+  padding: 0 0.58rem;
+  color: #475569;
+  font-size: 0.76rem;
+  font-weight: 850;
+  text-align: center;
+  box-shadow: none;
+}
+
+.image-canvas-editor__character-spec-ref {
+  min-width: 6rem;
+  border-style: solid;
+  border-color: rgba(147, 51, 234, 0.24);
+  background: #faf5ff;
+  color: #6b21a8;
+}
+
+.image-canvas-editor__character-spec-ref:hover,
+.image-canvas-editor__character-reference-add:hover {
+  transform: translateY(-1px);
+  border-color: #a78bfa;
+  background: #f5f3ff;
+  color: #5b21b6;
+}
+
+.image-canvas-editor__character-spec-ref:disabled,
+.image-canvas-editor__character-reference-add:disabled {
+  cursor: not-allowed;
+  opacity: 0.58;
+  transform: none;
+}
+
+.image-canvas-editor__character-spec-menu {
+  min-width: 9.4rem;
+  z-index: 24;
+}
+
+.image-canvas-editor__character-reference-add {
+  min-width: 3.55rem;
+  color: #64748b;
+}
+
+.image-canvas-editor__reference-tile {
+  display: inline-grid;
+  grid-template-columns: 2.25rem minmax(0, 1fr);
+  min-width: 8.4rem;
+  height: 3.75rem;
+  align-items: center;
+  justify-content: start;
+  gap: 0.48rem;
+  border-radius: 1.05rem;
+  padding: 0.34rem 0.62rem 0.34rem 0.4rem;
+  text-align: left;
+  box-shadow:
+    0 12px 28px rgba(15, 23, 42, 0.1),
+    inset 0 1px 0 rgba(255, 255, 255, 0.84);
+}
+
+.image-canvas-editor__reference-tile--spec {
+  max-width: 12rem;
+  border: 1px solid rgba(147, 51, 234, 0.22);
+  background: radial-gradient(
+      circle at 18% 20%,
+      rgba(216, 180, 254, 0.42),
+      transparent 38%
+    ),
+    linear-gradient(135deg, #fff7ff 0%, #f8fafc 100%);
+  color: #5b21b6;
+}
+
+.image-canvas-editor__reference-tile--upload {
+  max-width: 11.6rem;
+  border: 1px dashed rgba(75, 181, 170, 0.46);
+  background: radial-gradient(
+      circle at 18% 20%,
+      rgba(153, 246, 228, 0.42),
+      transparent 38%
+    ),
+    linear-gradient(135deg, #f0fdfa 0%, #f8fafc 100%);
+  color: #0f766e;
+}
+
+.image-canvas-editor__reference-tile-visual {
+  display: grid;
+  width: 2.25rem;
+  height: 2.25rem;
+  place-items: center;
+  overflow: hidden;
+  border-radius: 0.78rem;
+  background: rgba(255, 255, 255, 0.82);
+  color: currentColor;
+  box-shadow:
+    inset 0 0 0 1px rgba(148, 163, 184, 0.18),
+    0 8px 18px rgba(15, 23, 42, 0.08);
+}
+
+.image-canvas-editor__reference-tile-visual img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.image-canvas-editor__reference-tile-copy {
+  min-width: 0;
+  overflow: hidden;
+  color: currentColor;
+  font-size: 0.76rem;
+  font-weight: 900;
+  line-height: 1.12;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__character-ref-thumb {
+  position: relative;
+  flex: 0 0 auto;
+  width: 3.75rem;
+  height: 3.75rem;
+  overflow: hidden;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  border-radius: 1.05rem;
+  background: #f1f5f9;
+  box-shadow:
+    0 12px 28px rgba(15, 23, 42, 0.1),
+    inset 0 0 0 1px rgba(255, 255, 255, 0.72);
+}
+
+.image-canvas-editor__character-ref-thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.image-canvas-editor__character-ref-index {
+  position: absolute;
+  right: 0.24rem;
+  bottom: 0.22rem;
+  display: inline-flex;
+  min-width: 1.25rem;
+  height: 1.25rem;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid rgba(255, 255, 255, 0.74);
+  border-radius: 999px;
+  background: rgba(15, 23, 42, 0.76);
+  color: #ffffff;
+  font-size: 0.74rem;
+  font-weight: 900;
+  line-height: 1;
+}
+
+.image-canvas-editor__canvas-pick-hint {
+  position: absolute;
+  left: 50%;
+  top: 4.1rem;
+  z-index: 15;
+  max-width: min(30rem, calc(100% - 1.5rem));
+  border: 1px solid rgba(147, 51, 234, 0.22);
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.94);
+  padding: 0.48rem 0.78rem;
+  color: #581c87;
+  font-size: 0.78rem;
+  font-weight: 850;
+  text-align: center;
+  box-shadow: 0 14px 34px rgba(88, 28, 135, 0.16);
+  transform: translateX(-50%);
+  pointer-events: none;
+}
+
+.image-canvas-editor__spec-composer {
+  grid-template-columns: minmax(0, 1fr);
+  min-height: 0;
+}
+
+.image-canvas-editor__spec-composer.image-canvas-editor__generation-composer--image {
+  grid-template-rows: auto auto auto;
+}
+
+.image-canvas-editor__spec-fields {
+  grid-column: 1 / -1;
+  display: grid;
+  gap: 0.28rem;
+}
+
+.image-canvas-editor__spec-input {
+  min-height: 1.96rem;
+}
+
+.image-canvas-editor__spec-textarea {
+  min-height: 3.8rem;
+}
+
+.image-canvas-editor__spec-textarea--view {
+  min-height: 3.1rem;
+}
+
+.image-canvas-editor__spec-composer .image-canvas-editor__field-block {
+  gap: 0.24rem;
+}
+
+.image-canvas-editor__readonly-generation-option
+  .image-canvas-editor__option-cluster:disabled {
+  cursor: default;
+  opacity: 1;
+  color: #475569;
+  pointer-events: none;
+}
+
+.image-canvas-editor__readonly-generation-option
+  .image-canvas-editor__option-cluster:disabled:hover {
+  border-color: transparent;
+  background: transparent;
+  box-shadow: none;
+}
+
+.image-canvas-editor__context-menu {
+  position: fixed;
+  z-index: 35;
+  display: grid;
+  width: 11.75rem;
+  gap: 0.12rem;
+  border: 1px solid rgba(203, 213, 225, 0.95);
+  border-radius: 0.5rem;
+  background: #ffffff;
+  padding: 0.32rem;
+  box-shadow: 0 18px 44px rgba(15, 23, 42, 0.18);
+  color: #1f2937;
+}
+
+.image-canvas-editor__context-menu button {
+  display: flex;
+  width: 100%;
+  min-height: 1.82rem;
+  align-items: center;
+  justify-content: flex-start;
+  border: 0;
+  border-radius: 0.34rem;
+  background: transparent;
+  padding: 0 0.55rem;
+  color: inherit;
+  font-size: 0.78rem;
+  font-weight: 820;
+  text-align: left;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__context-menu button:hover:not(:disabled) {
+  background: #eef6ff;
+  color: #0f4a87;
+}
+
+.image-canvas-editor__context-menu button:disabled {
+  cursor: not-allowed;
+  color: #a3acba;
+}
+
+.image-canvas-editor__context-menu hr {
+  width: 100%;
+  height: 1px;
+  margin: 0.18rem 0;
+  border: 0;
+  background: #e2e8f0;
+}
+
+.image-canvas-editor__context-menu-item {
+  font-weight: 850;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__context-menu-danger {
+  color: #b42318 !important;
+}
+
+.image-canvas-editor__context-menu-danger:hover:not(:disabled) {
+  background: #fff1f2 !important;
+  color: #991b1b !important;
+}
+
+.image-canvas-editor__quick-edit-panel,
+.image-canvas-editor__crop-expand-panel {
+  position: absolute;
+  z-index: 14;
+  display: grid;
+  width: min(24rem, calc(100vw - 1.5rem));
+  max-height: min(32rem, calc(100% - 1.5rem));
+  gap: 0.58rem;
+  overflow: auto;
+  border: 1px solid rgba(148, 163, 184, 0.36);
+  border-radius: 1.1rem;
+  background: rgba(255, 255, 255, 0.96);
+  padding: 0.72rem;
+  color: #1f2937;
+  box-shadow: 0 22px 48px rgba(15, 23, 42, 0.22);
+  transform: translateX(-50%);
+}
+
+.image-canvas-editor__quick-edit-panel.image-canvas-editor__generation-composer {
+  width: min(42rem, calc(100vw - 1.5rem));
+  gap: 0.18rem 0.72rem;
+}
+
+.image-canvas-editor__generation-composer--quick-edit {
+  min-height: 11.8rem;
+}
+
+.image-canvas-editor__quick-edit-footer {
+  grid-template-columns: auto minmax(0, 1fr) auto auto;
+}
+
+.image-canvas-editor__quick-edit-footer
+  .image-canvas-editor__option-popover-anchor--model {
+  grid-column: 3;
+}
+
+.image-canvas-editor__quick-edit-footer
+  .image-canvas-editor__generation-submit {
+  grid-column: 4;
+}
+
+.image-canvas-editor__crop-expand-panel {
+  width: min(18.5rem, calc(100vw - 1.5rem));
+  transform: none;
+}
+
+.image-canvas-editor__crop-expand-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  color: #0f172a;
+  font-size: 0.92rem;
+}
+
+.image-canvas-editor__crop-expand-ratios {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.44rem;
+}
+
+.image-canvas-editor__crop-expand-ratio {
+  display: flex;
+  min-height: 2.35rem;
+  align-items: center;
+  gap: 0.46rem;
+  border: 1px solid rgba(148, 163, 184, 0.34);
+  border-radius: 0.72rem;
+  background: rgba(248, 250, 252, 0.92);
+  padding: 0 0.56rem;
+  color: #334155;
+  font-size: 0.78rem;
+  font-weight: 850;
+}
+
+.image-canvas-editor__crop-expand-ratio:hover {
+  border-color: rgba(59, 130, 246, 0.46);
+  background: #eff6ff;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__crop-expand-ratio--selected {
+  border-color: rgba(37, 99, 235, 0.76);
+  background: #dbeafe;
+  color: #1d4ed8;
+}
+
+.image-canvas-editor__crop-expand-ratio-shape {
+  width: 1.08rem;
+  height: 0.82rem;
+  flex: 0 0 auto;
+  border: 2px solid currentColor;
+  border-radius: 0.2rem;
+  opacity: 0.84;
+}
+
+.image-canvas-editor__crop-expand-ratio-shape--square {
+  width: 0.9rem;
+  height: 0.9rem;
+}
+
+.image-canvas-editor__crop-expand-ratio-shape--landscape {
+  width: 1.22rem;
+  height: 0.76rem;
+}
+
+.image-canvas-editor__crop-expand-ratio-shape--portrait {
+  width: 0.76rem;
+  height: 1.22rem;
+}
+
+.image-canvas-editor__crop-expand-actions {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.58rem;
+}
+
+.image-canvas-editor__quick-edit-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+}
+
+.image-canvas-editor__quick-edit-reference {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.5rem;
+  color: #334155;
+  font-size: 0.82rem;
+  font-weight: 850;
+}
+
+.image-canvas-editor__quick-edit-reference img {
+  width: 2.6rem;
+  height: 2.6rem;
+  flex: 0 0 auto;
+  border-radius: 0.72rem;
+  object-fit: cover;
+  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.16);
+}
+
+.image-canvas-editor__quick-edit-reference span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.image-canvas-editor__quick-edit-prompt {
+  min-height: 5.6rem;
+}
+
+.image-canvas-editor__quick-edit-controls {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.5rem;
+}
+
+.image-canvas-editor__quick-edit-submit {
+  justify-self: end;
+  min-width: 6.8rem;
+}
+
+.image-canvas-editor__crop-expand-error {
+  margin: 0;
+  border-radius: 0.72rem;
+  background: #fff1f2;
+  padding: 0.48rem 0.62rem;
+  color: #be123c;
+  font-size: 0.74rem;
+  font-weight: 800;
+}
+
+.image-canvas-editor__crop-expand-frame {
+  position: absolute;
+  z-index: 999;
+  box-sizing: border-box;
+  border: 2px solid #38bdf8;
+  background:
+    linear-gradient(90deg, rgba(14, 165, 233, 0.2) 1px, transparent 1px),
+    linear-gradient(rgba(14, 165, 233, 0.2) 1px, transparent 1px);
+  background-size: 33.333% 33.333%;
+  box-shadow:
+    0 0 0 99999px rgba(15, 23, 42, 0.18),
+    0 0 0 1px rgba(255, 255, 255, 0.72) inset;
+  pointer-events: none;
+}
+
+.image-canvas-editor__crop-expand-source-mask {
+  position: absolute;
+  border: 1px dashed rgba(255, 255, 255, 0.8);
+  background: rgba(255, 255, 255, 0.08);
+  pointer-events: none;
+}
+
+.image-canvas-editor__crop-expand-handle {
+  position: absolute;
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid #ffffff;
+  border-radius: 999px;
+  background: #0ea5e9;
+  box-shadow: 0 6px 16px rgba(14, 165, 233, 0.28);
+  pointer-events: auto;
+  touch-action: none;
+}
+
+.image-canvas-editor__crop-expand-handle::before {
+  position: absolute;
+  inset: -0.7rem;
+  content: '';
+}
+
+.image-canvas-editor__crop-expand-handle--top-left {
+  top: 0;
+  left: 0;
+  cursor: nwse-resize;
+  transform: translate(-50%, -50%);
+}
+
+.image-canvas-editor__crop-expand-handle--top {
+  top: 0;
+  left: 50%;
+  cursor: ns-resize;
+  transform: translate(-50%, -50%);
+}
+
+.image-canvas-editor__crop-expand-handle--top-right {
+  top: 0;
+  right: 0;
+  cursor: nesw-resize;
+  transform: translate(50%, -50%);
+}
+
+.image-canvas-editor__crop-expand-handle--right {
+  top: 50%;
+  right: 0;
+  cursor: ew-resize;
+  transform: translate(50%, -50%);
+}
+
+.image-canvas-editor__crop-expand-handle--bottom-right {
+  right: 0;
+  bottom: 0;
+  cursor: nwse-resize;
+  transform: translate(50%, 50%);
+}
+
+.image-canvas-editor__crop-expand-handle--bottom {
+  bottom: 0;
+  left: 50%;
+  cursor: ns-resize;
+  transform: translate(-50%, 50%);
+}
+
+.image-canvas-editor__crop-expand-handle--bottom-left {
+  bottom: 0;
+  left: 0;
+  cursor: nesw-resize;
+  transform: translate(-50%, 50%);
+}
+
+.image-canvas-editor__crop-expand-handle--left {
+  top: 50%;
+  left: 0;
+  cursor: ew-resize;
+  transform: translate(-50%, -50%);
+}
+
+.image-canvas-editor__character-animation-panel {
+  position: absolute;
+  z-index: 14;
+  display: grid;
+  width: min(42rem, calc(100vw - 1.5rem));
+  max-height: min(34rem, calc(100% - 1.5rem));
+  gap: 0.58rem;
+  overflow: auto;
+  border: 1px solid rgba(148, 163, 184, 0.36);
+  border-radius: 1.1rem;
+  background: rgba(255, 255, 255, 0.96);
+  padding: 0.76rem;
+  font-size: 0.82rem;
+  box-shadow: 0 22px 48px rgba(15, 23, 42, 0.22);
+}
+
+.image-canvas-editor__character-animation-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+  color: #1f2937;
+  font-size: 0.9rem;
+}
+
+.image-canvas-editor__character-animation-textarea {
+  grid-column: 1 / -1;
+  min-height: 8rem;
+}
+
+.image-canvas-editor__character-animation-presets {
+  display: flex;
+  grid-column: 1 / -1;
+  flex-wrap: wrap;
+  gap: 0.38rem;
+}
+
+.image-canvas-editor__character-animation-preset {
+  border: 1px solid rgba(148, 163, 184, 0.28);
+  border-radius: 999px;
+  background: #f8fafc;
+  padding: 0.34rem 0.58rem;
+  color: #334155;
+  font-size: 0.78rem;
+}
+
+.image-canvas-editor__character-animation-footer {
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.46rem;
+}
+
+.image-canvas-editor__character-animation-submit {
+  grid-column: 3;
+  min-width: 5.45rem;
+  height: 2.25rem;
+  gap: 0.4rem;
+  border: 0;
+  background: #0f172a;
+  color: #ffffff;
+}
+
+.image-canvas-editor__snap-guide {
+  position: absolute;
+  z-index: 7;
+  pointer-events: none;
+  background: #4bb5aa;
+  box-shadow: 0 0 0 1px rgba(75, 181, 170, 0.28);
+}
+
+.image-canvas-editor__snap-guide--vertical {
+  top: 0;
+  width: 2px;
+  height: 100%;
+  transform: translateX(-1px);
+}
+
+.image-canvas-editor__snap-guide--horizontal {
+  left: 0;
+  width: 100%;
+  height: 2px;
+  transform: translateY(-1px);
+}
+
+.image-canvas-editor__generate-dialog {
+  color: #1f2937;
+}
+
+.image-canvas-editor__metadata-dialog {
+  border: 1px solid rgba(226, 232, 240, 0.92);
+  background: #ffffff;
+  color: #1f2937;
+  box-shadow: 0 24px 70px rgba(15, 23, 42, 0.18);
+}
+
+.image-canvas-editor__metadata-body {
+  padding: 0;
+}
+
+.image-canvas-editor__generate-dialog-body {
+  padding: 0;
+}
+
+.image-canvas-editor__generate-form {
+  display: grid;
+}
+
+.image-canvas-editor__generate-body {
+  display: grid;
+  gap: 0.7rem;
+  padding: 0.85rem;
+}
+
+.image-canvas-editor__generate-prompt {
+  min-height: 7rem;
+  resize: vertical;
+  border: 1px solid #d9dee8;
+  border-radius: 0.45rem;
+  background: #f8fafc;
+  padding: 0.7rem;
+  color: #1f2937;
+  font: inherit;
+  font-size: 0.82rem;
+  font-weight: 720;
+  outline: none;
+}
+
+.image-canvas-editor__generate-prompt:focus {
+  border-color: #38bdf8;
+  background: #ffffff;
+  box-shadow: 0 0 0 3px rgba(56, 189, 248, 0.18);
+}
+
+.image-canvas-editor__generate-status {
+  margin: 0;
+}
+
+.image-canvas-editor__generate-status--floating {
+  position: absolute;
+  z-index: 14;
+  width: max-content;
+  min-width: 5.2rem;
+  transform: translateX(-50%);
+}
+
+.image-canvas-editor__generate-submit {
+  justify-self: end;
+}
+
+.image-canvas-editor__metadata-grid {
+  display: grid;
+  grid-template-columns: 5.5rem minmax(0, 1fr);
+  gap: 0.55rem 0.75rem;
+  margin: 0;
+  padding: 0.85rem;
+  font-size: 0.78rem;
+}
+
+.image-canvas-editor__metadata-grid dt {
+  color: #64748b;
+  font-weight: 820;
+}
+
+.image-canvas-editor__metadata-grid dd {
+  min-width: 0;
+  margin: 0;
+  overflow-wrap: anywhere;
+  color: #1f2937;
+  font-weight: 760;
+}
+
+.image-canvas-editor__metadata-inputs {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.42rem;
+}
+
+.image-canvas-editor__metadata-input-field {
+  display: grid;
+  gap: 0.16rem;
+}
+
+.image-canvas-editor__metadata-input-title {
+  color: #64748b;
+  font-size: 0.7rem;
+  font-weight: 820;
+}
+
+.image-canvas-editor__metadata-reference-list {
+  display: grid;
+  width: 100%;
+  gap: 0.42rem;
+}
+
+.image-canvas-editor__metadata-reference-card {
+  display: grid;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  border: 1px solid rgba(148, 163, 184, 0.26);
+  border-radius: 0.65rem;
+  background: rgba(248, 250, 252, 0.92);
+  padding: 0.38rem;
+}
+
+.image-canvas-editor__metadata-reference-copy {
+  display: grid;
+  min-width: 0;
+  gap: 0.12rem;
+}
+
+.image-canvas-editor__metadata-reference-id {
+  color: #64748b;
+  font-size: 0.72rem;
+  overflow-wrap: anywhere;
+}
+
+@media (max-width: 760px) {
+  .image-canvas-editor {
+    flex-direction: column;
+    gap: 0;
+  }
+
+  .image-canvas-editor__sidebar {
+    width: 100%;
+    min-width: 0;
+    max-height: 14rem;
+    flex-shrink: 0;
+    border-right: 0;
+    border-bottom: 1px solid #d9dee8;
+  }
+
+  .image-canvas-editor__asset-list {
+    grid-auto-flow: column;
+    grid-auto-columns: minmax(15rem, 78vw);
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+
+  .image-canvas-editor__layers-list {
+    grid-auto-flow: column;
+    grid-auto-columns: minmax(12.5rem, 70vw);
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+
+  .image-canvas-editor__quick-edit-panel,
+  .image-canvas-editor__character-animation-panel {
+    position: fixed;
+    left: 0.75rem !important;
+    right: 0.75rem;
+    top: auto !important;
+    bottom: 0.75rem;
+    width: auto;
+    max-height: min(72vh, 34rem);
+    transform: none;
+  }
+
+  .image-canvas-editor__quick-edit-panel.image-canvas-editor__generation-composer {
+    width: auto;
+    bottom: 3.85rem;
+  }
+
+  .image-canvas-editor__generation-composer {
+    position: fixed;
+    left: 0.75rem !important;
+    right: 0.75rem;
+    top: auto !important;
+    bottom: 3.85rem;
+    width: auto;
+    max-height: min(72vh, 31rem);
+    grid-template-columns: 3.55rem minmax(0, 1fr);
+    overflow: auto;
+    transform: none;
+  }
+
+  .image-canvas-editor__generation-composer-footer,
+  .image-canvas-editor__character-animation-footer {
+    grid-template-columns: minmax(0, 1fr);
+    align-items: stretch;
+  }
+
+  .image-canvas-editor__option-cluster--dimensions,
+  .image-canvas-editor__option-cluster--model,
+  .image-canvas-editor__readonly-generation-option,
+  .image-canvas-editor__generation-submit,
+  .image-canvas-editor__character-animation-submit {
+    grid-column: auto;
+    width: 100%;
+    max-width: none;
+    justify-self: stretch;
+  }
+
+  .image-canvas-editor__generation-submit {
+    width: 100%;
+  }
+
+  .image-canvas-editor__character-composer {
+    position: fixed;
+    left: 0.75rem !important;
+    right: 0.75rem;
+    top: auto !important;
+    bottom: 3.85rem;
+    width: auto;
+    max-height: min(72vh, 31rem);
+    overflow: auto;
+    padding: 0.58rem;
+    transform: none;
+  }
+
+  .image-canvas-editor__character-reference-row {
+    padding-right: 2rem;
+  }
+
+  .image-canvas-editor__character-spec-ref {
+    min-width: 5.4rem;
+  }
+
+  .image-canvas-editor__character-spec-ref,
+  .image-canvas-editor__character-reference-add,
+  .image-canvas-editor__character-ref-thumb {
+    height: 3.2rem;
+  }
+
+  .image-canvas-editor__character-ref-thumb {
+    width: 3.2rem;
+  }
+
+  .image-canvas-editor__icon-composer {
+    left: 0.75rem !important;
+    right: auto;
+    top: auto !important;
+    bottom: 3.85rem;
+    width: calc(100% - 1.5rem) !important;
+    min-width: 0;
+    transform: none;
+  }
+
+  .image-canvas-editor__canvas-pick-hint {
+    position: fixed;
+    top: 4.35rem;
+    max-width: calc(100% - 1.5rem);
+    border-radius: 0.9rem;
+  }
+
+  .image-canvas-editor__main {
+    min-height: 0;
+    flex: 1;
+  }
+
+  .image-canvas-editor__topbar {
+    min-height: 3.2rem;
+  }
+
+  .image-canvas-editor__title-block h1 {
+    font-size: 0.84rem;
+  }
+
+  .image-canvas-editor__floating-toolbar button,
+  .image-canvas-editor__bottom-toolbar button,
+  .image-canvas-editor__reset-button {
+    width: 2rem;
+    height: 2rem;
+  }
+
+  .image-canvas-editor__floating-toolbar button.image-canvas-editor__floating-toolbar-text-button {
+    width: auto;
+  }
+
+  .image-canvas-editor__floating-toolbar {
+    max-width: calc(100% - 1.5rem);
+    overflow-x: auto;
+  }
+
+  .image-canvas-editor__bottom-toolbar {
+    left: 0.75rem;
+    right: 0.75rem;
+    max-width: none;
+    transform: none;
+  }
+
+  .image-canvas-editor__panel-dock {
+    left: 0.75rem;
+    bottom: 3.85rem;
+  }
+
+  .image-canvas-editor__minimap {
+    left: 0.75rem;
+    bottom: 7rem;
+    width: 7.2rem;
+    height: 4.6rem;
+  }
+}
+
 .platform-bottom-nav {
   position: relative;
   box-sizing: border-box;
@@ -3875,6 +8912,12 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   }
 }
 
+.image-canvas-editor__panel-dock .image-canvas-editor__zoom-trigger {
+  width: auto;
+  min-width: 4.15rem;
+  padding: 0 0.65rem;
+}
+
 @keyframes baby-object-gift-lid-open {
   0% {
     transform: rotate(0deg) translateY(0);
@@ -6031,6 +11074,320 @@ html[data-mobile-keyboard-open='true'] .platform-mobile-bottom-dock {
   z-index: 1;
 }
 
+.creation-home-brand-lockup {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.7rem;
+}
+
+.creation-home-brand-lockup__art,
+.creation-home-nav-art,
+.creation-home-topbar-art {
+  display: none;
+}
+
+.platform-desktop-shell--workbench {
+  --creation-home-sidebar-width: 10rem;
+  border-color: rgba(221, 191, 166, 0.9);
+  border-radius: 1.85rem;
+  padding: 0 !important;
+  background:
+    linear-gradient(rgba(255, 250, 244, 0.72), rgba(255, 250, 244, 0.72)),
+    url('/creation-home/background-clay-workspace.png') center top / 64rem 64rem repeat,
+    linear-gradient(180deg, #fffaf4 0%, #fffdf9 52%, #fff8f0 100%);
+  box-shadow: 0 24px 58px rgba(112, 57, 30, 0.08);
+}
+
+.platform-desktop-shell--workbench::before {
+  display: none;
+}
+
+.platform-desktop-shell--workbench::after {
+  display: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-layout {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  height: 100%;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-leftbar {
+  width: var(--creation-home-sidebar-width);
+  min-height: 0;
+  border-right: 1px solid rgba(219, 190, 166, 0.72);
+  background: rgba(255, 250, 245, 0.46);
+  padding: 0.86rem 0.5rem 0.96rem;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-main {
+  min-height: 0;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar {
+  display: flex;
+  gap: 0.58rem;
+  min-height: 3.62rem;
+  border: 0;
+  border-bottom: 1px solid rgba(219, 190, 166, 0.72);
+  border-radius: 0;
+  background: rgba(255, 250, 245, 0.54);
+  padding: 0.42rem 1rem !important;
+  box-shadow: none;
+  backdrop-filter: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar::before {
+  display: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar__brand-search {
+  gap: 0.58rem !important;
+  justify-content: flex-start;
+  padding-left: clamp(3.1rem, 5.8vw, 8.2rem);
+}
+
+.platform-desktop-shell--workbench .platform-brand-logo {
+  align-self: center;
+}
+
+.platform-desktop-shell--workbench .creation-home-brand-lockup {
+  align-self: flex-start;
+  gap: 0.42rem;
+  min-height: 3.28rem;
+  padding-left: 0.28rem;
+}
+
+.platform-desktop-shell--workbench .creation-home-brand-lockup__art {
+  display: block;
+  width: 2.58rem;
+  height: 2.58rem;
+  flex: 0 0 auto;
+  border-radius: 999px;
+  object-fit: cover;
+  object-position: center;
+  filter: drop-shadow(0 0.36rem 0.34rem rgba(112, 62, 32, 0.18));
+  mix-blend-mode: multiply;
+}
+
+.platform-desktop-shell--workbench .platform-brand-logo__title {
+  font-size: 1.38rem;
+  color: #4a220f;
+}
+
+.platform-desktop-shell--workbench .platform-brand-logo__subtitle {
+  color: #9b5a35;
+  font-size: 0.46rem;
+}
+
+.platform-desktop-shell--workbench
+  .platform-desktop-topbar__brand-search
+  > .platform-desktop-search {
+  width: 100%;
+  max-width: 20rem !important;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar__actions {
+  align-self: center;
+  gap: 0.5rem !important;
+  margin-left: auto;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-search {
+  position: relative;
+  box-sizing: border-box;
+  min-height: 0;
+  height: 2.36rem;
+  border: 1px solid rgba(214, 184, 159, 0.92);
+  background: rgba(255, 250, 244, 0.78);
+  box-shadow: none;
+}
+
+.platform-desktop-shell--workbench
+  .platform-desktop-topbar__brand-search
+  > .platform-desktop-search {
+  padding-block: 0 !important;
+  padding-inline: 0.64rem 0.58rem !important;
+  gap: 0.48rem !important;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-create-wallet-chip {
+  position: relative;
+  min-height: 2.28rem;
+  border-radius: 999px !important;
+  padding-inline: 0.42rem 0.58rem !important;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-create-wallet-chip::after {
+  position: absolute;
+  top: 50%;
+  right: -0.52rem;
+  width: 1px;
+  height: 1.66rem;
+  background: rgba(217, 190, 166, 0.82);
+  content: "";
+  transform: translateY(-50%);
+}
+
+.platform-desktop-shell--workbench .creation-home-topbar-art {
+  display: block;
+  flex: 0 0 auto;
+  object-fit: cover;
+  object-position: center;
+  filter: drop-shadow(0 0.18rem 0.18rem rgba(112, 62, 32, 0.14));
+  mix-blend-mode: multiply;
+}
+
+.platform-desktop-shell--workbench .creation-home-topbar-art--search {
+  width: 1.34rem;
+  height: 1.34rem;
+  margin: -0.16rem -0.26rem -0.16rem -0.34rem;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-search > svg {
+  display: none;
+}
+
+.platform-desktop-shell--workbench .creation-home-topbar-art--wallet {
+  width: 1.32rem;
+  height: 1.32rem;
+  margin: -0.14rem -0.18rem -0.14rem -0.3rem;
+}
+
+.platform-desktop-shell--workbench
+  .platform-desktop-create-wallet-chip
+  .platform-icon-badge {
+  display: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search {
+  width: auto;
+  max-width: none !important;
+  min-width: 7.35rem;
+  height: 2.3rem;
+  border-color: transparent;
+  background: transparent;
+  padding-inline: 0.34rem 0.42rem;
+  gap: 0.38rem !important;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search:hover {
+  border-color: rgba(214, 184, 159, 0.52);
+  background: rgba(255, 250, 244, 0.56);
+}
+
+.platform-desktop-shell--workbench .platform-desktop-topbar button.platform-desktop-search > span:first-child {
+  width: 2.06rem;
+  height: 2.06rem;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail {
+  align-self: flex-start;
+  width: 7.05rem;
+  margin: 1.12rem auto 0;
+  border-color: rgba(220, 192, 168, 0.7);
+  border-radius: 1.55rem;
+  background: rgba(255, 250, 244, 0.54);
+  padding: 0.38rem;
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.72),
+    0 18px 34px rgba(112, 57, 30, 0.08);
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button {
+  min-height: 2.88rem;
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-start;
+  gap: 0.34rem;
+  border-radius: 0.82rem;
+  padding: 0 0.34rem;
+  text-align: left;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button--primary {
+  min-height: 2.88rem;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__icon-shell {
+  width: 2.08rem;
+  height: 2.08rem;
+  flex: 0 0 auto;
+  border-radius: 0.74rem;
+  background: transparent;
+  box-shadow: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon-shell {
+  background:
+    radial-gradient(circle at 35% 22%, rgba(255, 196, 133, 0.72), transparent 42%),
+    linear-gradient(180deg, #df884b 0%, #c6652a 100%);
+  box-shadow:
+    0 0.62rem 1rem rgba(139, 73, 32, 0.18),
+    inset 0 1px 0 rgba(255, 255, 255, 0.5);
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon {
+  color: #fffaf3;
+}
+
+.platform-desktop-shell--workbench .creation-home-nav-art {
+  display: block;
+  width: 1.62rem;
+  height: 1.62rem;
+  object-fit: contain;
+  object-position: center;
+  filter: drop-shadow(0 0.3rem 0.28rem rgba(112, 62, 32, 0.14));
+  mix-blend-mode: multiply;
+}
+
+.platform-desktop-shell--workbench
+  .platform-desktop-rail__button--active
+  .creation-home-nav-art {
+  filter:
+    saturate(0.34)
+    brightness(1.68)
+    contrast(0.82)
+    drop-shadow(0 0.22rem 0.2rem rgba(112, 62, 32, 0.18));
+  mix-blend-mode: screen;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__icon {
+  display: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button--active {
+  border-color: transparent;
+  background: transparent;
+  box-shadow: none;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__label {
+  color: #c15f28;
+}
+
+.platform-desktop-shell--workbench .platform-desktop-rail__label {
+  font-size: 0.78rem;
+  font-weight: 820;
+  letter-spacing: 0;
+}
+
+.platform-desktop-shell--workbench .platform-tab-panel-stack {
+  min-height: 0;
+  background: transparent;
+}
+
+.platform-desktop-shell--workbench .platform-tab-panel {
+  height: 100%;
+  overflow: auto;
+  padding-right: 0;
+}
+
+.platform-desktop-shell--workbench .creation-landing {
+  background: transparent;
+}
+
 .platform-desktop-trending-item {
   position: relative;
   overflow: hidden;
@@ -10128,3 +15485,25 @@ button {
 ::-webkit-scrollbar-thumb:hover {
   background: #3f3f46;
 }
+
+.image-canvas-editor__metadata-dialog.platform-modal-shell {
+  border-color: rgba(226, 232, 240, 0.92) !important;
+  background: #ffffff !important;
+  color: #1f2937 !important;
+  box-shadow: 0 24px 70px rgba(15, 23, 42, 0.18) !important;
+}
+
+.image-canvas-editor__generation-composer .image-canvas-editor__option-cluster {
+  min-height: 2.25rem;
+  background: transparent;
+  border-color: transparent;
+}
+
+.image-canvas-editor__generation-composer
+  .image-canvas-editor__option-cluster:hover:not(:disabled),
+.image-canvas-editor__generation-composer
+  .image-canvas-editor__option-cluster[aria-expanded='true'] {
+  border-color: rgba(15, 23, 42, 0.08);
+  background: #f8fafc;
+  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.08);
+}
diff --git a/src/index.test.ts b/src/index.test.ts
index f24f246db..5e3ff9310 100644
--- a/src/index.test.ts
+++ b/src/index.test.ts
@@ -31,6 +31,23 @@ function getCssBlock(source: string, selector: string) {
 }
 
 describe('index stylesheet unread dots', () => {
+  it('keeps creation home primary rail styling separate from active tab styling', () => {
+    const css = readIndexCss();
+
+    expect(css).not.toContain(
+      '.platform-desktop-shell--workbench .platform-desktop-rail__button--primary .platform-desktop-rail__icon-shell,\n.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon-shell',
+    );
+    expect(css).not.toContain(
+      '.platform-desktop-shell--workbench .platform-desktop-rail__button--primary .platform-desktop-rail__label,\n.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__label',
+    );
+    expect(css).toContain(
+      '.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__icon-shell',
+    );
+    expect(css).toContain(
+      '.platform-desktop-shell--workbench .platform-desktop-rail__button--active .platform-desktop-rail__label',
+    );
+  });
+
   it('hides the outer page scrollbar without changing inner scroll helpers', () => {
     const css = readIndexCss();
 
diff --git a/src/routing/appPageRoutes.test.ts b/src/routing/appPageRoutes.test.ts
index a80fcb8d4..955dc7203 100644
--- a/src/routing/appPageRoutes.test.ts
+++ b/src/routing/appPageRoutes.test.ts
@@ -21,6 +21,37 @@ describe('appPageRoutes', () => {
     );
   });
 
+  it('resolves the image editor route', () => {
+    expect(resolveSelectionStageFromPath('/editor/canvas')).toBe(
+      'image-editor',
+    );
+    expect(resolveSelectionStageFromPath('/EDITOR/CANVAS/')).toBe(
+      'image-editor',
+    );
+    expect(resolvePathForSelectionStage('image-editor')).toBe('/editor/canvas');
+  });
+
+  it('preserves project id when navigating to an editor canvas project', () => {
+    window.history.replaceState(null, '', '/creation');
+
+    pushAppHistoryPath('/editor/canvas?projectid=project-from-route-test');
+
+    expect(window.location.pathname).toBe('/editor/canvas');
+    expect(window.location.search).toBe('?projectid=project-from-route-test');
+  });
+
+  it('resolves the project route', () => {
+    expect(resolveSelectionStageFromPath('/project')).toBe('project');
+    expect(resolveSelectionStageFromPath('/PROJECT/')).toBe('project');
+    expect(resolvePathForSelectionStage('project')).toBe('/project');
+  });
+
+  it('resolves the creation home route', () => {
+    expect(resolveSelectionStageFromPath('/creation')).toBe('creation-home');
+    expect(resolveSelectionStageFromPath('/CREATION/')).toBe('creation-home');
+    expect(resolvePathForSelectionStage('creation-home')).toBe('/creation');
+  });
+
   it('resolves jump-hop creation, gallery and runtime routes', () => {
     expect(resolveSelectionStageFromPath('/creation/jump-hop')).toBe(
       'jump-hop-workspace',
@@ -58,9 +89,9 @@ describe('appPageRoutes', () => {
     expect(resolveSelectionStageFromPath('/creation/puzzle-clear')).toBe(
       'puzzle-clear-workspace',
     );
-    expect(resolveSelectionStageFromPath('/creation/puzzle-clear/generating')).toBe(
-      'puzzle-clear-generating',
-    );
+    expect(
+      resolveSelectionStageFromPath('/creation/puzzle-clear/generating'),
+    ).toBe('puzzle-clear-generating');
     expect(resolveSelectionStageFromPath('/creation/puzzle-clear/result')).toBe(
       'puzzle-clear-result',
     );
@@ -85,9 +116,9 @@ describe('appPageRoutes', () => {
     expect(resolveSelectionStageFromPath('/creation/wooden-fish')).toBe(
       'wooden-fish-workspace',
     );
-    expect(resolveSelectionStageFromPath('/creation/wooden-fish/generating')).toBe(
-      'wooden-fish-generating',
-    );
+    expect(
+      resolveSelectionStageFromPath('/creation/wooden-fish/generating'),
+    ).toBe('wooden-fish-generating');
     expect(resolveSelectionStageFromPath('/creation/wooden-fish/result')).toBe(
       'wooden-fish-result',
     );
diff --git a/src/routing/appPageRoutes.ts b/src/routing/appPageRoutes.ts
index e041db4b4..0d8b349dc 100644
--- a/src/routing/appPageRoutes.ts
+++ b/src/routing/appPageRoutes.ts
@@ -11,6 +11,9 @@ export const PUBLIC_WORK_QUERY_PARAM = 'work';
 
 const STAGE_ROUTE_ENTRIES = [
   ['platform', '/'],
+  ['creation-home', '/creation'],
+  ['project', '/project'],
+  ['image-editor', '/editor/canvas'],
   ['profile-feedback', '/profile/feedback'],
   ['work-detail', '/works/detail'],
   ['detail', '/worlds/detail'],
@@ -98,6 +101,20 @@ export function resolveSelectionStageFromPath(
   return ROUTE_STAGE_BY_PATH.get(normalizeAppPath(pathname)) ?? 'platform';
 }
 
+export function resolveInitialSelectionStageFromPath(
+  pathname: string,
+  isDesktopLayout: boolean,
+): SelectionStage {
+  const normalizedPath = normalizeAppPath(pathname);
+  const selectionStage = resolveSelectionStageFromPath(pathname);
+
+  if (normalizedPath === '/' && isDesktopLayout) {
+    return 'creation-home';
+  }
+
+  return selectionStage;
+}
+
 export function resolvePathForSelectionStage(stage: SelectionStage) {
   return APP_STAGE_ROUTES[stage] ?? APP_STAGE_ROUTES.platform;
 }
diff --git a/src/services/image-editor/editorImageReference.test.ts b/src/services/image-editor/editorImageReference.test.ts
new file mode 100644
index 000000000..20f53954b
--- /dev/null
+++ b/src/services/image-editor/editorImageReference.test.ts
@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  compressEditorImageReferenceDataUrlForGeneration,
+  resolveEditorImageReferenceDataUrl,
+} from './editorImageReference';
+
+describe('editorImageReference', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('passes through base64 image data urls without fetching', async () => {
+    vi.spyOn(globalThis, 'fetch');
+
+    await expect(
+      resolveEditorImageReferenceDataUrl('data:image/png;base64,c291cmNl'),
+    ).resolves.toBe('data:image/png;base64,c291cmNl');
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it('converts public image paths to base64 image data urls', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(new Uint8Array([104, 101, 108, 108, 111]), {
+        status: 200,
+        headers: {
+          'Content-Type': 'image/webp',
+        },
+      }),
+    );
+
+    await expect(
+      resolveEditorImageReferenceDataUrl(
+        '/creation-type-references/puzzle.webp',
+      ),
+    ).resolves.toBe('data:image/webp;base64,aGVsbG8=');
+  });
+
+  it('keeps generation references unchanged when browser canvas is unavailable', async () => {
+    await expect(
+      compressEditorImageReferenceDataUrlForGeneration(
+        'data:image/png;base64,large-reference',
+      ),
+    ).resolves.toBe('data:image/png;base64,large-reference');
+  });
+});
diff --git a/src/services/image-editor/editorImageReference.ts b/src/services/image-editor/editorImageReference.ts
new file mode 100644
index 000000000..ce23faa35
--- /dev/null
+++ b/src/services/image-editor/editorImageReference.ts
@@ -0,0 +1,134 @@
+import { readAssetBytes } from '../assetReadUrlService';
+
+const GENERATION_REFERENCE_MAX_EDGE = 1280;
+const GENERATION_REFERENCE_QUALITY = 0.82;
+const GENERATION_REFERENCE_MIME_TYPE = 'image/jpeg';
+
+type EditorImageReferenceCompressionOptions = {
+  maxEdge?: number;
+  quality?: number;
+  mimeType?: string;
+};
+
+function normalizeImageContentType(contentType: string | null) {
+  const mimeType = contentType?.split(';')[0]?.trim().toLowerCase() ?? '';
+  return mimeType.startsWith('image/') ? mimeType : 'image/png';
+}
+
+function encodeBytesAsBase64(bytes: Uint8Array) {
+  let binary = '';
+  const chunkSize = 0x8000;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(
+      ...bytes.subarray(offset, offset + chunkSize),
+    );
+  }
+  return btoa(binary);
+}
+
+/**
+ * 图片画布的生成编辑接口只接收图片 Data URL。
+ * 画布里既有上传 / 生成图，也有内置 public 参考图和历史 generated 路径；
+ * 提交给后端前统一读取成 Data URL，避免后端误收到普通 URL 后进入 Data URL 校验错误。
+ */
+export async function resolveEditorImageReferenceDataUrl(
+  source: string,
+  signal?: AbortSignal,
+) {
+  const normalizedSource = source.trim();
+  if (!normalizedSource) {
+    throw new Error('图片参考图不能为空');
+  }
+  if (normalizedSource.startsWith('data:image/')) {
+    return normalizedSource;
+  }
+  if (normalizedSource.startsWith('data:')) {
+    throw new Error('图片参考图必须是图片 Data URL');
+  }
+
+  const response = await readAssetBytes(normalizedSource, {
+    signal,
+    expireSeconds: 300,
+  });
+  const mimeType = normalizeImageContentType(
+    response.headers.get('Content-Type'),
+  );
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength <= 0) {
+    throw new Error('图片参考图为空');
+  }
+
+  return `data:${mimeType};base64,${encodeBytesAsBase64(bytes)}`;
+}
+
+function loadImageDataUrl(dataUrl: string) {
+  return new Promise<HTMLImageElement>((resolve, reject) => {
+    if (typeof Image === 'undefined') {
+      reject(new Error('当前环境不支持图片压缩'));
+      return;
+    }
+
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new Error('参考图读取失败'));
+    image.src = dataUrl;
+  });
+}
+
+export async function compressEditorImageReferenceDataUrlForGeneration(
+  dataUrl: string,
+  options: EditorImageReferenceCompressionOptions = {},
+) {
+  if (!dataUrl.startsWith('data:image/') || typeof document === 'undefined') {
+    return dataUrl;
+  }
+
+  const maxEdge = Math.max(1, options.maxEdge ?? GENERATION_REFERENCE_MAX_EDGE);
+  const quality = Math.min(
+    1,
+    Math.max(0.1, options.quality ?? GENERATION_REFERENCE_QUALITY),
+  );
+  const mimeType = options.mimeType ?? GENERATION_REFERENCE_MIME_TYPE;
+
+  try {
+    const image = await loadImageDataUrl(dataUrl);
+    const sourceWidth = image.naturalWidth || image.width;
+    const sourceHeight = image.naturalHeight || image.height;
+    if (sourceWidth <= 0 || sourceHeight <= 0) {
+      return dataUrl;
+    }
+
+    const scale = Math.min(1, maxEdge / Math.max(sourceWidth, sourceHeight));
+    const targetWidth = Math.max(1, Math.round(sourceWidth * scale));
+    const targetHeight = Math.max(1, Math.round(sourceHeight * scale));
+    const canvas = document.createElement('canvas');
+    canvas.width = targetWidth;
+    canvas.height = targetHeight;
+    const context = canvas.getContext('2d');
+    if (!context) {
+      return dataUrl;
+    }
+
+    // 中文注释：参考图只用于模型理解视觉方向，提交前压缩可避免原图 Data URL 撑爆 JSON 请求体。
+    if (mimeType === 'image/jpeg') {
+      context.fillStyle = '#fff';
+      context.fillRect(0, 0, targetWidth, targetHeight);
+    }
+    context.drawImage(image, 0, 0, targetWidth, targetHeight);
+    const compressed = canvas.toDataURL(mimeType, quality);
+    return compressed.startsWith('data:image/') &&
+      compressed.length < dataUrl.length
+      ? compressed
+      : dataUrl;
+  } catch {
+    return dataUrl;
+  }
+}
+
+export async function resolveEditorImageReferenceDataUrlForGeneration(
+  source: string,
+  signal?: AbortSignal,
+) {
+  const dataUrl = await resolveEditorImageReferenceDataUrl(source, signal);
+  return compressEditorImageReferenceDataUrlForGeneration(dataUrl);
+}
diff --git a/src/services/image-editor/editorMediaAssetUploadClient.test.ts b/src/services/image-editor/editorMediaAssetUploadClient.test.ts
new file mode 100644
index 000000000..58c06ea47
--- /dev/null
+++ b/src/services/image-editor/editorMediaAssetUploadClient.test.ts
@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { requestJson } from '../apiClient';
+import { getSignedAssetReadUrl } from '../assetReadUrlService';
+import { uploadEditorMediaAssetFile } from './editorMediaAssetUploadClient';
+
+vi.mock('../apiClient', () => ({
+  requestJson: vi.fn(),
+}));
+
+vi.mock('../assetReadUrlService', () => ({
+  getSignedAssetReadUrl: vi.fn(),
+}));
+
+const requestJsonMock = vi.mocked(requestJson);
+const getSignedAssetReadUrlMock = vi.mocked(getSignedAssetReadUrl);
+
+describe('editorMediaAssetUploadClient', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(Date, 'now').mockReturnValue(1771400000000);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(null, { status: 200 })),
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('uploads editor MP4 assets through direct OSS upload and confirms object metadata', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({
+        upload: {
+          bucket: 'bucket',
+          host: 'https://oss.example.com',
+          objectKey:
+            'generated-character-drafts/editor/asset-library/video/demo.mp4',
+          legacyPublicPath:
+            '/generated-character-drafts/editor/asset-library/video/demo.mp4',
+          formFields: {
+            key: 'generated-character-drafts/editor/asset-library/video/demo.mp4',
+            policy: 'policy',
+            'x-oss-signature': 'signature',
+          },
+        },
+      })
+      .mockResolvedValueOnce({
+        assetObject: {
+          assetObjectId: 'assetobj-video',
+          objectKey:
+            'generated-character-drafts/editor/asset-library/video/demo.mp4',
+          assetKind: 'editor_uploaded_video',
+        },
+      });
+    getSignedAssetReadUrlMock.mockResolvedValueOnce(
+      'https://signed.example.com/demo.mp4',
+    );
+
+    const result = await uploadEditorMediaAssetFile(
+      new File(['video'], 'demo.mp4', { type: 'video/mp4' }),
+      'video',
+    );
+
+    const ticketBody = JSON.parse(
+      (requestJsonMock.mock.calls[0]?.[1] as RequestInit).body as string,
+    );
+    expect(ticketBody).toMatchObject({
+      legacyPrefix: 'generated-character-drafts',
+      pathSegments: ['editor', 'asset-library', 'video', '1771400000000'],
+      fileName: 'demo.mp4',
+      contentType: 'video/mp4',
+      access: 'private',
+      maxSizeBytes: 5,
+      successActionStatus: 200,
+      metadata: {
+        asset_kind: 'editor_uploaded_video',
+        editor_media_type: 'video',
+      },
+    });
+    expect(fetch).toHaveBeenCalledWith(
+      'https://oss.example.com',
+      expect.objectContaining({
+        method: 'POST',
+        body: expect.any(FormData),
+      }),
+    );
+    const confirmBody = JSON.parse(
+      (requestJsonMock.mock.calls[1]?.[1] as RequestInit).body as string,
+    );
+    expect(confirmBody).toMatchObject({
+      bucket: 'bucket',
+      objectKey: 'generated-character-drafts/editor/asset-library/video/demo.mp4',
+      contentType: 'video/mp4',
+      contentLength: 5,
+      assetKind: 'editor_uploaded_video',
+      accessPolicy: 'private',
+      entityId: 'editor-asset-library-video',
+    });
+    expect(getSignedAssetReadUrlMock).toHaveBeenCalledWith(
+      {
+        objectKey:
+          'generated-character-drafts/editor/asset-library/video/demo.mp4',
+        expireSeconds: 3600,
+      },
+      undefined,
+      { bypassCache: true },
+    );
+    expect(result).toEqual({
+      src: 'https://signed.example.com/demo.mp4',
+      objectKey:
+        'generated-character-drafts/editor/asset-library/video/demo.mp4',
+      assetObjectId: 'assetobj-video',
+      legacyPublicPath:
+        '/generated-character-drafts/editor/asset-library/video/demo.mp4',
+    });
+  });
+});
diff --git a/src/services/image-editor/editorMediaAssetUploadClient.ts b/src/services/image-editor/editorMediaAssetUploadClient.ts
new file mode 100644
index 000000000..bced35b7e
--- /dev/null
+++ b/src/services/image-editor/editorMediaAssetUploadClient.ts
@@ -0,0 +1,139 @@
+import { requestJson } from '../apiClient';
+import { getSignedAssetReadUrl } from '../assetReadUrlService';
+
+export type EditorMediaAssetUploadType = 'video' | 'audio';
+
+type DirectUploadTicketResponse = {
+  upload: {
+    bucket: string;
+    host: string;
+    objectKey: string;
+    legacyPublicPath: string;
+    formFields: Record<string, string | null | undefined>;
+  };
+};
+
+type ConfirmAssetObjectResponse = {
+  assetObject: {
+    assetObjectId: string;
+    objectKey: string;
+    assetKind: string;
+  };
+};
+
+export type UploadedEditorMediaAsset = {
+  src: string;
+  objectKey: string;
+  assetObjectId: string;
+  legacyPublicPath: string;
+};
+
+const EDITOR_MEDIA_READ_EXPIRE_SECONDS = 60 * 60;
+
+function resolveEditorMediaAssetKind(mediaType: EditorMediaAssetUploadType) {
+  return mediaType === 'video'
+    ? 'editor_uploaded_video'
+    : 'editor_uploaded_audio';
+}
+
+function resolveFallbackFileName(mediaType: EditorMediaAssetUploadType) {
+  return mediaType === 'video' ? 'editor-video.mp4' : 'editor-audio.mp3';
+}
+
+function sanitizeEditorMediaFileName(
+  fileName: string,
+  mediaType: EditorMediaAssetUploadType,
+) {
+  const trimmedName = fileName.trim();
+  return trimmedName || resolveFallbackFileName(mediaType);
+}
+
+async function postDirectUploadFile(
+  upload: DirectUploadTicketResponse['upload'],
+  file: File,
+) {
+  const formData = new FormData();
+  Object.entries(upload.formFields).forEach(([key, value]) => {
+    if (value !== null && value !== undefined) {
+      formData.append(key, value);
+    }
+  });
+  formData.append('file', file, file.name);
+
+  const response = await fetch(upload.host, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!response.ok) {
+    throw new Error('上传素材失败');
+  }
+}
+
+export async function uploadEditorMediaAssetFile(
+  file: File,
+  mediaType: EditorMediaAssetUploadType,
+): Promise<UploadedEditorMediaAsset> {
+  const assetKind = resolveEditorMediaAssetKind(mediaType);
+  const fileName = sanitizeEditorMediaFileName(file.name, mediaType);
+  const contentType = file.type.trim() || 'application/octet-stream';
+
+  const ticket = await requestJson<DirectUploadTicketResponse>(
+    '/api/assets/direct-upload-tickets',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        legacyPrefix: 'generated-character-drafts',
+        pathSegments: ['editor', 'asset-library', mediaType, `${Date.now()}`],
+        fileName,
+        contentType,
+        access: 'private',
+        maxSizeBytes: file.size,
+        successActionStatus: 200,
+        metadata: {
+          asset_kind: assetKind,
+          editor_media_type: mediaType,
+        },
+      }),
+    },
+    '创建素材上传凭证失败',
+  );
+
+  await postDirectUploadFile(ticket.upload, file);
+
+  const confirmed = await requestJson<ConfirmAssetObjectResponse>(
+    '/api/assets/objects/confirm',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bucket: ticket.upload.bucket,
+        objectKey: ticket.upload.objectKey,
+        contentType,
+        contentLength: file.size,
+        assetKind,
+        accessPolicy: 'private',
+        entityId: `editor-asset-library-${mediaType}`,
+      }),
+    },
+    '确认素材资产失败',
+  );
+
+  // 中文注释：素材库立即预览使用短期 signed URL；持久化仍记录 legacy path 和 objectKey。
+  const signedUrl = await getSignedAssetReadUrl(
+    {
+      objectKey: confirmed.assetObject.objectKey,
+      expireSeconds: EDITOR_MEDIA_READ_EXPIRE_SECONDS,
+    },
+    undefined,
+    { bypassCache: true },
+  );
+
+  return {
+    src: signedUrl,
+    objectKey: confirmed.assetObject.objectKey,
+    assetObjectId: confirmed.assetObject.assetObjectId,
+    legacyPublicPath: ticket.upload.legacyPublicPath,
+  };
+}
diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts
new file mode 100644
index 000000000..88f124dd0
--- /dev/null
+++ b/src/services/image-editor/editorProjectClient.test.ts
@@ -0,0 +1,1284 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createEditorAsset,
+  createEditorAssetFolder,
+  createEditorProject,
+  createEditorProjectResource,
+  deleteEditorAsset,
+  deleteEditorAssetFolder,
+  deleteEditorProject,
+  editEditorImage,
+  extractEditorUiDesignAssets,
+  generateEditorBackgroundMusic,
+  generateEditorCharacterAnimation,
+  generateEditorIconSpritesheet,
+  generateEditorImage,
+  generateEditorSoundEffect,
+  generateEditorVideo,
+  listEditorProjects,
+  loadEditorAssetLibrary,
+  loadEditorProject,
+  loadOrCreateRecentEditorProject,
+  renameEditorProject,
+  saveEditorProjectLayout,
+  updateEditorAsset,
+  updateEditorAssetFolder,
+} from './editorProjectClient';
+
+const requestJsonMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../apiClient', () => ({
+  requestJson: requestJsonMock,
+}));
+
+describe('editorProjectClient', () => {
+  afterEach(() => {
+    requestJsonMock.mockReset();
+  });
+
+  it('loads the recent project without creating a duplicate when it exists', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      project: {
+        projectId: 'editor-project-1',
+        title: '未命名画布',
+        canvas: {
+          canvasId: 'editor-project-1:canvas:default',
+          projectId: 'editor-project-1',
+          title: '默认画布',
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+        viewport: { x: 0, y: 0, scale: 1 },
+        layers: [],
+        resources: [],
+        updatedAt: '2026-06-12T00:00:00.000Z',
+      },
+    });
+
+    const project = await loadOrCreateRecentEditorProject();
+
+    expect(project.projectId).toBe('editor-project-1');
+    expect(requestJsonMock).toHaveBeenCalledTimes(1);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects/recent',
+      { method: 'GET' },
+      '读取图片画布工程失败',
+    );
+  });
+
+  it('creates a default project when there is no recent project', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({ project: null })
+      .mockResolvedValueOnce({
+        project: {
+          projectId: 'editor-project-created',
+          title: '未命名画布',
+          canvas: {
+            canvasId: 'editor-project-created:canvas:default',
+            projectId: 'editor-project-created',
+            title: '默认画布',
+            viewport: { x: 0, y: 0, scale: 1 },
+            layers: [],
+            updatedAt: '2026-06-12T00:00:00.000Z',
+          },
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          resources: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+      });
+
+    const project = await loadOrCreateRecentEditorProject();
+
+    expect(project.projectId).toBe('editor-project-created');
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/editor/projects',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: '未命名画布' }),
+      }),
+      '创建图片画布工程失败',
+    );
+  });
+
+  it('saves viewport and layer layout through the project API', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      project: {
+        projectId: 'editor-project-1',
+        title: '未命名画布',
+        canvas: {
+          canvasId: 'editor-project-1:canvas:default',
+          projectId: 'editor-project-1',
+          title: '默认画布',
+          viewport: { x: 12, y: 24, scale: 0.5 },
+          layers: [
+            { layerId: 'layer-1', resourceId: 'resource-1', x: 10, y: 20 },
+          ],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+        viewport: { x: 12, y: 24, scale: 0.5 },
+        layers: [
+          { layerId: 'layer-1', resourceId: 'resource-1', x: 10, y: 20 },
+        ],
+        resources: [],
+        updatedAt: '2026-06-12T00:00:00.000Z',
+      },
+    });
+
+    await saveEditorProjectLayout('editor-project-1', {
+      viewport: { x: 12, y: 24, scale: 0.5 },
+      layers: [{ layerId: 'layer-1', resourceId: 'resource-1', x: 10, y: 20 }],
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects/editor-project-1',
+      expect.objectContaining({
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          viewport: { x: 12, y: 24, scale: 0.5 },
+          layers: [
+            { layerId: 'layer-1', resourceId: 'resource-1', x: 10, y: 20 },
+          ],
+        }),
+      }),
+      '保存图片画布工程失败',
+    );
+  });
+
+  it('lists editor projects from the project API', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      projects: [
+        {
+          projectId: 'editor-project-1',
+          title: '角色设定板',
+          canvas: {
+            canvasId: 'editor-project-1:canvas:default',
+            projectId: 'editor-project-1',
+            title: '默认画布',
+            viewport: { x: 0, y: 0, scale: 1 },
+            layers: [],
+            updatedAt: '2026-06-12T00:00:00.000Z',
+          },
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          resources: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+      ],
+    });
+
+    const projects = await listEditorProjects();
+
+    expect(projects).toHaveLength(1);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects',
+      { method: 'GET' },
+      '读取图片画布工程列表失败',
+    );
+  });
+
+  it('loads an explicit project by id', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      project: {
+        projectId: 'editor-project-1',
+        title: '角色设定板',
+        canvas: {
+          canvasId: 'editor-project-1:canvas:default',
+          projectId: 'editor-project-1',
+          title: '默认画布',
+          viewport: { x: 8, y: 9, scale: 1.5 },
+          layers: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+        viewport: { x: 8, y: 9, scale: 1.5 },
+        layers: [],
+        resources: [],
+        updatedAt: '2026-06-12T00:00:00.000Z',
+      },
+    });
+
+    const project = await loadEditorProject('editor-project-1');
+
+    expect(project.viewport.scale).toBe(1.5);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects/editor-project-1',
+      { method: 'GET' },
+      '读取图片画布工程失败',
+    );
+  });
+
+  it('renames and deletes an editor project', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({
+        project: {
+          projectId: 'editor-project-1',
+          title: '新标题',
+          canvas: {
+            canvasId: 'editor-project-1:canvas:default',
+            projectId: 'editor-project-1',
+            title: '默认画布',
+            viewport: { x: 0, y: 0, scale: 1 },
+            layers: [],
+            updatedAt: '2026-06-12T00:00:00.000Z',
+          },
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          resources: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+      })
+      .mockResolvedValueOnce({ deletedProjectId: 'editor-project-1' });
+
+    await renameEditorProject('editor-project-1', '新标题');
+    await deleteEditorProject('editor-project-1');
+
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/editor/projects/editor-project-1/metadata',
+      expect.objectContaining({
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: '新标题' }),
+      }),
+      '重命名图片画布工程失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/editor/projects/editor-project-1',
+      { method: 'DELETE' },
+      '删除图片画布工程失败',
+    );
+  });
+
+  it('creates a resource with upload or generated metadata', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      resource: {
+        resourceId: 'resource-generated-1',
+        projectId: 'editor-project-1',
+        imageSrc: '/generated-editor-assets/project/image.png',
+        objectKey: 'generated-editor-assets/project/image.png',
+        width: 2048,
+        height: 2048,
+        sourceType: 'generated',
+        prompt: 'dragon knight',
+        model: 'gpt-image-2',
+      },
+    });
+
+    await createEditorProjectResource('editor-project-1', {
+      imageSrc: '/generated-editor-assets/project/image.png',
+      objectKey: 'generated-editor-assets/project/image.png',
+      width: 2048,
+      height: 2048,
+      sourceType: 'generated',
+      prompt: 'dragon knight',
+      model: 'gpt-image-2',
+      sourceResourceId: 'resource-source',
+      assetKind: 'character',
+      generationInputs: {
+        fields: [{ title: '角色设定', value: 'dragon knight' }],
+        references: [],
+      },
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects/editor-project-1/resources',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          imageSrc: '/generated-editor-assets/project/image.png',
+          objectKey: 'generated-editor-assets/project/image.png',
+          width: 2048,
+          height: 2048,
+          sourceType: 'generated',
+          prompt: 'dragon knight',
+          model: 'gpt-image-2',
+          sourceResourceId: 'resource-source',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: 'dragon knight' }],
+            references: [],
+          },
+        }),
+      }),
+      '创建图片画布资源失败',
+    );
+  });
+
+  it('loads and mutates the account-level asset library', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({
+        library: {
+          folders: [
+            {
+              folderId: 'folder-project',
+              label: '项目素材',
+              sortOrder: 0,
+              collapsed: false,
+              systemDefault: true,
+            },
+          ],
+          assets: [],
+        },
+      })
+      .mockResolvedValueOnce({
+        folder: {
+          folderId: 'folder-role',
+          label: '角色',
+          sortOrder: 100,
+          collapsed: false,
+          systemDefault: false,
+        },
+      })
+      .mockResolvedValueOnce({
+        folder: {
+          folderId: 'folder-role',
+          label: '角色参考',
+          sortOrder: 100,
+          collapsed: true,
+          systemDefault: false,
+        },
+      })
+      .mockResolvedValueOnce({
+        library: {
+          folders: [],
+          assets: [],
+        },
+      });
+
+    await loadEditorAssetLibrary();
+    await createEditorAssetFolder('角色', 100);
+    await updateEditorAssetFolder('folder-role', {
+      label: '角色参考',
+      collapsed: true,
+    });
+    await deleteEditorAssetFolder('folder-role');
+
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/editor/assets/library',
+      { method: 'GET' },
+      '读取图片画布素材库失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/editor/assets/folders',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ label: '角色', sortOrder: 100 }),
+      }),
+      '创建图片画布素材文件夹失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      3,
+      '/api/editor/assets/folders/folder-role',
+      expect.objectContaining({
+        method: 'PATCH',
+        body: JSON.stringify({ label: '角色参考', collapsed: true }),
+      }),
+      '更新图片画布素材文件夹失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      4,
+      '/api/editor/assets/folders/folder-role',
+      { method: 'DELETE' },
+      '删除图片画布素材文件夹失败',
+    );
+  });
+
+  it('creates, updates, and deletes account-level image assets', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({
+        asset: {
+          assetId: 'asset-1',
+          folderId: 'folder-project',
+          label: '主视觉.png',
+          imageSrc: 'data:image/png;base64,ZmFrZQ==',
+          width: 640,
+          height: 480,
+          sourceType: 'uploaded',
+        },
+      })
+      .mockResolvedValueOnce({
+        asset: {
+          assetId: 'asset-1',
+          folderId: 'folder-role',
+          label: '角色主视觉.png',
+          imageSrc: 'data:image/png;base64,ZmFrZQ==',
+          width: 640,
+          height: 480,
+          sourceType: 'uploaded',
+        },
+      })
+      .mockResolvedValueOnce({
+        asset: {
+          assetId: 'asset-1',
+          folderId: 'folder-role',
+          label: '角色主视觉.png',
+          imageSrc: 'data:image/png;base64,ZmFrZQ==',
+          width: 640,
+          height: 480,
+          sourceType: 'uploaded',
+        },
+      });
+
+    await createEditorAsset({
+      folderId: 'folder-project',
+      label: '主视觉.png',
+      imageSrc: 'data:image/png;base64,ZmFrZQ==',
+      width: 640,
+      height: 480,
+      sourceType: 'uploaded',
+      assetKind: 'icon',
+      generationInputs: {
+        fields: [{ title: '素材描述', value: '返回按钮' }],
+        references: [],
+      },
+    });
+    await updateEditorAsset('asset-1', {
+      label: '角色主视觉.png',
+      folderId: 'folder-role',
+    });
+    await deleteEditorAsset('asset-1');
+
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/editor/assets',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({
+          folderId: 'folder-project',
+          label: '主视觉.png',
+          imageSrc: 'data:image/png;base64,ZmFrZQ==',
+          width: 640,
+          height: 480,
+          sourceType: 'uploaded',
+          assetKind: 'icon',
+          generationInputs: {
+            fields: [{ title: '素材描述', value: '返回按钮' }],
+            references: [],
+          },
+        }),
+      }),
+      '创建图片画布素材失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/editor/assets/asset-1',
+      expect.objectContaining({
+        method: 'PATCH',
+        body: JSON.stringify({
+          label: '角色主视觉.png',
+          folderId: 'folder-role',
+        }),
+      }),
+      '更新图片画布素材失败',
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      3,
+      '/api/editor/assets/asset-1',
+      { method: 'DELETE' },
+      '删除图片画布素材失败',
+    );
+  });
+
+  it('creates an explicit project from title input', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      project: {
+        projectId: 'editor-project-explicit',
+        title: '角色设定板',
+        canvas: {
+          canvasId: 'editor-project-explicit:canvas:default',
+          projectId: 'editor-project-explicit',
+          title: '默认画布',
+          viewport: { x: 0, y: 0, scale: 1 },
+          layers: [],
+          updatedAt: '2026-06-12T00:00:00.000Z',
+        },
+        viewport: { x: 0, y: 0, scale: 1 },
+        layers: [],
+        resources: [],
+        updatedAt: '2026-06-12T00:00:00.000Z',
+      },
+    });
+
+    await createEditorProject({ title: '角色设定板' });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/projects',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: '角色设定板' }),
+      }),
+      '创建图片画布工程失败',
+    );
+  });
+
+  it('generates editor images through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,abc',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '一张画布图片',
+      actualPrompt: '一张画布图片',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-task-1',
+    });
+
+    const result = await generateEditorImage({ prompt: '一张画布图片' });
+
+    expect(result.taskId).toBe('vector-task-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ prompt: '一张画布图片' }),
+      }),
+      '生成图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('passes image model options to editor image generation', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,character',
+      width: 1024,
+      height: 1536,
+      sourceType: 'generated',
+      prompt: '角色设定',
+      actualPrompt: '角色设定',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-character-1',
+    });
+
+    await generateEditorImage({
+      prompt: '角色设定',
+      kind: 'character',
+      model: 'gpt-image-2',
+      aspectRatio: '2:3',
+      imageSize: '1K',
+      projectId: 'editor-project-1',
+      assetKind: 'character',
+      assetFolderId: 'project',
+      assetLabel: '角色形象',
+      sourceResourceId: 'resource-spec-1',
+      generationInputs: {
+        fields: [{ title: '角色设定', value: '角色设定' }],
+        references: [],
+      },
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '角色设定',
+          kind: 'character',
+          model: 'gpt-image-2',
+          aspectRatio: '2:3',
+          imageSize: '1K',
+          projectId: 'editor-project-1',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '角色设定', value: '角色设定' }],
+            references: [],
+          },
+          assetFolderId: 'project',
+          assetLabel: '角色形象',
+          sourceResourceId: 'resource-spec-1',
+        }),
+      }),
+      '生成图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('passes canvas completion context to editor image generation', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,character',
+      width: 1024,
+      height: 1536,
+      sourceType: 'generated',
+      prompt: '角色设定',
+      actualPrompt: '角色设定',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-character-1',
+      project: null,
+    });
+
+    await generateEditorImage({
+      prompt: '角色设定',
+      kind: 'character',
+      projectId: 'editor-project-1',
+      assetKind: 'character',
+      canvasCompletion: {
+        dialogId: 'generation-dialog-1',
+        title: '角色形象 1',
+        placeholder: {
+          x: 120,
+          y: 140,
+          width: 420,
+          height: 560,
+          originalWidth: 1024,
+          originalHeight: 1536,
+        },
+      },
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/generations',
+      expect.objectContaining({
+        body: JSON.stringify({
+          prompt: '角色设定',
+          kind: 'character',
+          projectId: 'editor-project-1',
+          assetKind: 'character',
+          canvasCompletion: {
+            dialogId: 'generation-dialog-1',
+            title: '角色形象 1',
+            placeholder: {
+              x: 120,
+              y: 140,
+              width: 420,
+              height: 560,
+              originalWidth: 1024,
+              originalHeight: 1536,
+            },
+          },
+        }),
+      }),
+      '生成图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('generates icon spritesheets through the dedicated backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,sheet',
+      spritesheetWidth: 512,
+      spritesheetHeight: 512,
+      iconImageSrcs: [
+        {
+          name: '返回按钮',
+          imageSrc: 'data:image/png;base64,back',
+          width: 96,
+          height: 96,
+        },
+      ],
+      prompt: '图标素材 prompt',
+      actualPrompt: '图标素材 prompt',
+      model: 'gemini-3.1-flash-image-preview',
+      provider: 'VectorEngine',
+      taskId: 'icon-spritesheet-task-1',
+      priceMudPoints: 12,
+    });
+
+    const result = await generateEditorIconSpritesheet({
+      referenceImageSrc: 'data:image/png;base64,spec',
+      iconDescriptions: ['返回按钮', '设置按钮'],
+      priceMudPoints: 12,
+    });
+
+    expect(result.taskId).toBe('icon-spritesheet-task-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/icon-spritesheets/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          referenceImageSrc: 'data:image/png;base64,spec',
+          iconDescriptions: ['返回按钮', '设置按钮'],
+          model: 'gemini-3.1-flash-image-preview',
+          priceMudPoints: 12,
+        }),
+      }),
+      '生成图标素材失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('passes image model options to icon spritesheet generation', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,sheet',
+      spritesheetWidth: 1024,
+      spritesheetHeight: 1024,
+      iconImageSrcs: [],
+      prompt: '图标素材 prompt',
+      actualPrompt: '图标素材 prompt',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'icon-spritesheet-task-2',
+      priceMudPoints: 20,
+    });
+
+    await generateEditorIconSpritesheet({
+      referenceImageSrc: 'data:image/png;base64,spec',
+      iconDescriptions: ['返回按钮'],
+      model: 'gpt-image-2',
+      aspectRatio: '1:1',
+      imageSize: '2K',
+      priceMudPoints: 20,
+      projectId: 'editor-project-1',
+      assetFolderId: 'project',
+      generationInputs: {
+        fields: [{ title: '素材描述', value: '返回按钮' }],
+        references: [],
+      },
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/icon-spritesheets/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          referenceImageSrc: 'data:image/png;base64,spec',
+          iconDescriptions: ['返回按钮'],
+          model: 'gpt-image-2',
+          aspectRatio: '1:1',
+          imageSize: '2K',
+          priceMudPoints: 20,
+          projectId: 'editor-project-1',
+          generationInputs: {
+            fields: [{ title: '素材描述', value: '返回按钮' }],
+            references: [],
+          },
+          assetFolderId: 'project',
+        }),
+      }),
+      '生成图标素材失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('extracts UI design assets through the dedicated backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      spritesheetImageSrc: 'data:image/png;base64,ui-sheet',
+      spritesheetWidth: 1024,
+      spritesheetHeight: 1024,
+      iconImageSrcs: [
+        {
+          name: '素材 1',
+          imageSrc: 'data:image/png;base64,asset-1',
+          width: 128,
+          height: 128,
+        },
+      ],
+      prompt: '提取画面中的所有独立并整理成spritesheet',
+      actualPrompt: '提取画面中的所有独立并整理成spritesheet',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'ui-asset-extraction-1',
+      priceMudPoints: 20,
+    });
+
+    const result = await extractEditorUiDesignAssets({
+      sourceImageSrc: 'data:image/png;base64,ui-design',
+      projectId: 'editor-project-1',
+      assetFolderId: 'project',
+      spritesheetLabel: '战斗UI设计图 素材图集',
+      generationInputs: {
+        fields: [{ title: '来源', value: '战斗UI设计图' }],
+        references: [],
+      },
+    });
+
+    expect(result.taskId).toBe('ui-asset-extraction-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/ui-designs/assets/extractions',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          sourceImageSrc: 'data:image/png;base64,ui-design',
+          projectId: 'editor-project-1',
+          generationInputs: {
+            fields: [{ title: '来源', value: '战斗UI设计图' }],
+            references: [],
+          },
+          assetFolderId: 'project',
+          spritesheetLabel: '战斗UI设计图 素材图集',
+        }),
+      }),
+      '提取UI设计图素材失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('passes spec generation size and kind to the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,spec',
+      width: 2048,
+      height: 1152,
+      sourceType: 'generated',
+      prompt: '生成规范图',
+      actualPrompt: '生成规范图',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-spec-1',
+    });
+
+    const result = await generateEditorImage({
+      prompt: '生成规范图',
+      size: '2048x1152',
+      kind: 'spec',
+      model: 'gpt-image-2',
+    });
+
+    expect(result.width).toBe(2048);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '生成规范图',
+          size: '2048x1152',
+          kind: 'spec',
+          model: 'gpt-image-2',
+        }),
+      }),
+      '生成图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('passes publication material generation kind and size to the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,publication',
+      width: 720,
+      height: 1280,
+      sourceType: 'generated',
+      prompt: '宣发素材 prompt',
+      actualPrompt: '宣发素材 prompt',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-publication-1',
+    });
+
+    const result = await generateEditorImage({
+      prompt: '宣发素材 prompt',
+      size: '720x1280',
+      kind: 'publication-material',
+      aspectRatio: '9:16',
+      imageSize: '1K',
+      referenceImageSrcs: ['data:image/png;base64,ref'],
+    });
+
+    expect(result.height).toBe(1280);
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '宣发素材 prompt',
+          size: '720x1280',
+          kind: 'publication-material',
+          aspectRatio: '9:16',
+          imageSize: '1K',
+          referenceImageSrcs: ['data:image/png;base64,ref'],
+        }),
+      }),
+      '生成图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('generates editor character animations through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      taskId: 'character-animation-1',
+      model: 'seedance2.0-fast',
+      prompt: '生成游戏角色动画\n动作描述：\n待机',
+      previewVideoPath: '/generated-character-drafts/editor/preview.mp4',
+      frames: [
+        {
+          frameIndex: 1,
+          imageSrc: '/generated-character-drafts/editor/frame01.png',
+          width: 1024,
+          height: 1024,
+        },
+      ],
+      frameCount: 32,
+      durationSeconds: 4,
+      fps: 8,
+      priceMudPoints: 40,
+    });
+
+    const result = await generateEditorCharacterAnimation({
+      sourceLayerId: 'layer-character',
+      sourceImageSrc: 'data:image/png;base64,character',
+      sourceWidth: 1024,
+      sourceHeight: 1024,
+      promptText: '待机',
+      resolution: '480p',
+      ratio: 'same',
+      frameCount: 32,
+      durationSeconds: 4,
+      priceMudPoints: 40,
+      model: 'seedance2.0-fast',
+    });
+
+    expect(result.taskId).toBe('character-animation-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/character-animations/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          sourceLayerId: 'layer-character',
+          sourceImageSrc: 'data:image/png;base64,character',
+          sourceWidth: 1024,
+          sourceHeight: 1024,
+          promptText: '待机',
+          resolution: '480p',
+          ratio: 'same',
+          frameCount: 32,
+          durationSeconds: 4,
+          priceMudPoints: 40,
+          model: 'seedance2.0-fast',
+        }),
+      }),
+      '生成角色动画失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('generates editor videos through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      videoSrc: '/generated-editor-videos/video-task-1/preview.mp4',
+      width: 1280,
+      height: 720,
+      sourceType: 'generated',
+      prompt: '让角色向镜头挥手',
+      actualPrompt: '让角色向镜头挥手',
+      model: 'kling3.0-omni',
+      provider: 'VectorEngine',
+      taskId: 'video-task-1',
+      durationSeconds: 5,
+      resolution: '480p',
+      priceMudPoints: 100,
+    });
+
+    const result = await generateEditorVideo({
+      prompt: '让角色向镜头挥手',
+      model: 'kling3.0-omni',
+      aspectRatio: '16:9',
+      durationSeconds: 5,
+      resolution: '480p',
+      mode: 'std',
+      sound: 'off',
+      priceMudPoints: 100,
+    });
+
+    expect(result.taskId).toBe('video-task-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/videos/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '让角色向镜头挥手',
+          model: 'kling3.0-omni',
+          aspectRatio: '16:9',
+          durationSeconds: 5,
+          resolution: '480p',
+          mode: 'std',
+          sound: 'off',
+          webSearchEnabled: true,
+          priceMudPoints: 100,
+        }),
+      }),
+      '生成视频失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+
+  it('passes seedance video multimodal references through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      videoSrc: '/generated-editor-videos/video-task-2/preview.mp4',
+      width: 1280,
+      height: 720,
+      sourceType: 'generated',
+      prompt: '参考素材生成视频',
+      actualPrompt: '参考素材生成视频',
+      model: 'seedance2.0-fast',
+      provider: 'VectorEngine',
+      taskId: 'video-task-2',
+      durationSeconds: 5,
+      resolution: '720p',
+      priceMudPoints: 100,
+    });
+
+    await generateEditorVideo({
+      prompt: '参考素材生成视频',
+      model: 'seedance2.0-fast',
+      aspectRatio: '16:9',
+      durationSeconds: 5,
+      resolution: '720p',
+      mode: 'std',
+      sound: 'off',
+      priceMudPoints: 100,
+      referenceImageSrcs: ['data:image/png;base64,image'],
+      referenceVideoSrcs: [
+        'generated-character-drafts/editor/seedance-references/video/video.mp4',
+      ],
+      referenceAudioSrcs: [
+        'generated-character-drafts/editor/seedance-references/audio/audio.mp3',
+      ],
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/videos/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '参考素材生成视频',
+          model: 'seedance2.0-fast',
+          aspectRatio: '16:9',
+          durationSeconds: 5,
+          resolution: '720p',
+          mode: 'std',
+          sound: 'off',
+          webSearchEnabled: true,
+          priceMudPoints: 100,
+          referenceImageSrcs: ['data:image/png;base64,image'],
+          referenceVideoSrcs: [
+            'generated-character-drafts/editor/seedance-references/video/video.mp4',
+          ],
+          referenceAudioSrcs: [
+            'generated-character-drafts/editor/seedance-references/audio/audio.mp3',
+          ],
+        }),
+      }),
+      '生成视频失败',
+      expect.objectContaining({ timeoutMs: 1_200_000 }),
+    );
+  });
+
+  it('generates editor sound effects through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      audioSrc: '/generated-character-drafts/editor-audios/sfx.mp3',
+      width: 420,
+      height: 120,
+      sourceType: 'generated',
+      prompt: '金币掉落叮当声',
+      actualPrompt: '金币掉落叮当声',
+      model: 'audio1.0',
+      provider: 'VectorEngine',
+      taskId: 'sound-task-1',
+      priceMudPoints: 10,
+      audioKind: 'sound-effect',
+    });
+
+    const result = await generateEditorSoundEffect({
+      prompt: '金币掉落叮当声',
+      model: 'audio1.0',
+      duration: 7,
+      priceMudPoints: 10,
+    });
+
+    expect(result.taskId).toBe('sound-task-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/audios/sound-effects/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '金币掉落叮当声',
+          model: 'audio1.0',
+          duration: 7,
+          priceMudPoints: 10,
+        }),
+      }),
+      '生成游戏音效失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('sends editor sound effect duration to Vidu instead of legacy type and tempo', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      audioSrc: '/generated-character-drafts/editor-audios/sfx-null.mp3',
+      width: 420,
+      height: 120,
+      sourceType: 'generated',
+      prompt: '按钮确认短促音',
+      actualPrompt: '按钮确认短促音',
+      model: 'audio1.0',
+      provider: 'VectorEngine',
+      taskId: 'sound-task-null',
+      priceMudPoints: 10,
+      audioKind: 'sound-effect',
+    });
+
+    await generateEditorSoundEffect({
+      prompt: '按钮确认短促音',
+      model: 'audio1.0',
+      duration: 5,
+      priceMudPoints: 10,
+    });
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/audios/sound-effects/generations',
+      expect.objectContaining({
+        body: JSON.stringify({
+          prompt: '按钮确认短促音',
+          model: 'audio1.0',
+          duration: 5,
+          priceMudPoints: 10,
+        }),
+      }),
+      '生成游戏音效失败',
+      expect.any(Object),
+    );
+  });
+
+  it('generates editor background music through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      audioSrc: '/generated-character-drafts/editor-audios/bgm.mp3',
+      width: 420,
+      height: 120,
+      sourceType: 'generated',
+      prompt: '森林冒险背景音乐',
+      actualPrompt: '森林冒险背景音乐',
+      model: 'chirp-v4',
+      provider: 'VectorEngine',
+      taskId: 'music-task-1',
+      priceMudPoints: 5,
+      audioKind: 'background-music',
+    });
+
+    const result = await generateEditorBackgroundMusic({
+      gptDescriptionPrompt: '森林冒险背景音乐',
+      makeInstrumental: true,
+      priceMudPoints: 5,
+    });
+
+    expect(result.taskId).toBe('music-task-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/audios/background-music/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          gptDescriptionPrompt: '森林冒险背景音乐',
+          makeInstrumental: true,
+          priceMudPoints: 5,
+        }),
+      }),
+      '生成游戏背景音乐失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+
+  it('edits editor images through the backend BFF', async () => {
+    requestJsonMock.mockResolvedValueOnce({
+      imageSrc: 'data:image/png;base64,edited',
+      width: 1024,
+      height: 1024,
+      sourceType: 'generated',
+      prompt: '把画面改成黄昏光线',
+      actualPrompt: '把画面改成黄昏光线',
+      model: 'gpt-image-2',
+      provider: 'VectorEngine',
+      taskId: 'vector-edit-1',
+    });
+
+    const result = await editEditorImage({
+      prompt: '把画面改成黄昏光线',
+      sourceImageSrc: 'data:image/png;base64,source',
+      size: '1024x1024',
+      model: 'gpt-image-2',
+      projectId: 'editor-project-1',
+      assetKind: 'character',
+      assetFolderId: 'project',
+      assetLabel: '角色形象 修改结果',
+      sourceResourceId: 'resource-character-1',
+      generationInputs: {
+        fields: [{ title: '修改提示词', value: '把画面改成黄昏光线' }],
+        references: [],
+      },
+    });
+
+    expect(result.taskId).toBe('vector-edit-1');
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/editor/images/edits',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          prompt: '把画面改成黄昏光线',
+          sourceImageSrc: 'data:image/png;base64,source',
+          size: '1024x1024',
+          model: 'gpt-image-2',
+          projectId: 'editor-project-1',
+          assetKind: 'character',
+          generationInputs: {
+            fields: [{ title: '修改提示词', value: '把画面改成黄昏光线' }],
+            references: [],
+          },
+          assetFolderId: 'project',
+          assetLabel: '角色形象 修改结果',
+          sourceResourceId: 'resource-character-1',
+        }),
+      }),
+      '修改图片失败',
+      expect.objectContaining({
+        timeoutMs: 1_200_000,
+        retry: { maxRetries: 0 },
+      }),
+    );
+  });
+});
diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts
new file mode 100644
index 000000000..656f37efc
--- /dev/null
+++ b/src/services/image-editor/editorProjectClient.ts
@@ -0,0 +1,827 @@
+import { requestJson } from '../apiClient';
+
+const EDITOR_PROJECT_API_BASE = '/api/editor/projects';
+const EDITOR_ASSET_API_BASE = '/api/editor/assets';
+const EDITOR_IMAGE_GENERATION_API = '/api/editor/images/generations';
+const EDITOR_IMAGE_EDIT_API = '/api/editor/images/edits';
+const EDITOR_ICON_SPRITESHEET_GENERATION_API =
+  '/api/editor/icon-spritesheets/generations';
+const EDITOR_UI_DESIGN_ASSET_EXTRACTION_API =
+  '/api/editor/ui-designs/assets/extractions';
+const EDITOR_CHARACTER_ANIMATION_GENERATION_API =
+  '/api/editor/character-animations/generations';
+const EDITOR_VIDEO_GENERATION_API = '/api/editor/videos/generations';
+const EDITOR_SOUND_EFFECT_GENERATION_API =
+  '/api/editor/audios/sound-effects/generations';
+const EDITOR_BACKGROUND_MUSIC_GENERATION_API =
+  '/api/editor/audios/background-music/generations';
+const EDITOR_IMAGE_MODEL_NANOBANANA2 = 'gemini-3.1-flash-image-preview';
+const DEFAULT_PROJECT_TITLE = '未命名画布';
+
+export type EditorCanvasViewport = {
+  x: number;
+  y: number;
+  scale: number;
+};
+
+export type EditorProjectLayerSnapshot = Record<string, unknown> & {
+  layerId: string;
+  resourceId: string;
+};
+
+export type EditorAssetGenerationInputField = {
+  title: string;
+  value: string;
+};
+
+export type EditorAssetGenerationInputReference = {
+  title: string;
+  label: string;
+  refType: 'project-resource' | 'asset';
+  refId: string;
+};
+
+export type EditorAssetGenerationInputs = {
+  fields: EditorAssetGenerationInputField[];
+  references: EditorAssetGenerationInputReference[];
+};
+
+export type EditorProjectResourceSourceType =
+  | 'uploaded'
+  | 'generated'
+  | 'mock_generated';
+
+export type EditorProjectResourceSnapshot = {
+  resourceId: string;
+  projectId: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: EditorProjectResourceSourceType;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  durationSeconds?: number | null;
+  sourceResourceId?: string | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type EditorAssetFolderSnapshot = {
+  folderId: string;
+  label: string;
+  sortOrder: number;
+  collapsed: boolean;
+  systemDefault: boolean;
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type EditorAssetSnapshot = {
+  assetId: string;
+  folderId: string;
+  label: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: EditorProjectResourceSourceType;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  durationSeconds?: number | null;
+  sourceResourceId?: string | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+export type EditorAssetLibrarySnapshot = {
+  folders: EditorAssetFolderSnapshot[];
+  assets: EditorAssetSnapshot[];
+};
+
+export type EditorImageGenerationInput = {
+  prompt: string;
+  size?: string;
+  kind?:
+    | 'spec'
+    | 'character'
+    | 'quick-edit'
+    | 'ui-design'
+    | 'publication-material';
+  model?: string;
+  aspectRatio?: string;
+  imageSize?: string;
+  referenceImageSrcs?: string[];
+  projectId?: string | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  assetFolderId?: string | null;
+  assetLabel?: string | null;
+  sourceResourceId?: string | null;
+  canvasCompletion?: EditorCanvasGenerationCompletionInput | null;
+};
+
+export type EditorCanvasGenerationCompletionInput = {
+  dialogId: string;
+  title: string;
+  placeholder: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+  };
+};
+
+export type EditorIconSpritesheetGenerationInput = {
+  referenceImageSrc: string;
+  iconDescriptions: string[];
+  model?: string;
+  aspectRatio?: string;
+  imageSize?: string;
+  priceMudPoints: number;
+  projectId?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  assetFolderId?: string | null;
+};
+
+export type EditorUiDesignAssetExtractionInput = {
+  sourceImageSrc: string;
+  projectId?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  assetFolderId?: string | null;
+  spritesheetLabel?: string | null;
+};
+
+export type EditorImageEditInput = {
+  prompt: string;
+  sourceImageSrc: string;
+  size?: string;
+  model?: string;
+  projectId?: string | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+  assetFolderId?: string | null;
+  assetLabel?: string | null;
+  sourceResourceId?: string | null;
+};
+
+export type EditorImageGenerationResult = {
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: 'generated';
+  prompt: string;
+  actualPrompt?: string | null;
+  model: string;
+  provider: string;
+  taskId: string;
+  resource?: EditorProjectResourceSnapshot | null;
+  asset?: EditorAssetSnapshot | null;
+  project?: EditorProjectSnapshot | null;
+};
+
+export type EditorIconSpritesheetIconResult = {
+  name: string;
+  imageSrc: string;
+  width: number;
+  height: number;
+  resource?: EditorProjectResourceSnapshot | null;
+  asset?: EditorAssetSnapshot | null;
+};
+
+export type EditorIconSpritesheetGenerationResult = {
+  spritesheetImageSrc: string;
+  spritesheetWidth: number;
+  spritesheetHeight: number;
+  iconImageSrcs: EditorIconSpritesheetIconResult[];
+  prompt: string;
+  actualPrompt?: string | null;
+  model: string;
+  provider: string;
+  taskId: string;
+  priceMudPoints: number;
+  spritesheetResource?: EditorProjectResourceSnapshot | null;
+  spritesheetAsset?: EditorAssetSnapshot | null;
+};
+
+export type EditorCharacterAnimationResolution = '480p' | '720p';
+
+export type EditorCharacterAnimationRatio =
+  | 'same'
+  | '1:1'
+  | '4:3'
+  | '16:9'
+  | '9:16'
+  | '3:4';
+
+export type EditorCharacterAnimationFrameCount = 32 | 40 | 48;
+
+export type EditorCharacterAnimationDurationSeconds = 4 | 5 | 6;
+
+export type EditorCharacterAnimationGenerationInput = {
+  sourceLayerId: string;
+  sourceImageSrc: string;
+  sourceWidth: number;
+  sourceHeight: number;
+  promptText: string;
+  resolution: EditorCharacterAnimationResolution;
+  ratio: EditorCharacterAnimationRatio;
+  frameCount: EditorCharacterAnimationFrameCount;
+  durationSeconds: EditorCharacterAnimationDurationSeconds;
+  priceMudPoints: number;
+  model: 'seedance2.0-fast';
+};
+
+export type EditorCharacterAnimationFrameResult = {
+  frameIndex: number;
+  imageSrc: string;
+  width: number;
+  height: number;
+};
+
+export type EditorCharacterAnimationGenerationResult = {
+  taskId: string;
+  model: 'seedance2.0-fast';
+  prompt: string;
+  previewVideoPath: string;
+  frames: EditorCharacterAnimationFrameResult[];
+  frameCount: number;
+  durationSeconds: number;
+  fps: number;
+  priceMudPoints: number;
+};
+
+export type EditorVideoModel =
+  | 'seedance2.0'
+  | 'seedance2.0-fast'
+  | 'kling3.0'
+  | 'kling3.0-omni'
+  | 'veo3.1'
+  | 'veo3.1-fast';
+
+export type EditorVideoResolution = '480p' | '720p' | '1080p';
+export type EditorVideoSoundMode = 'on' | 'off';
+export type EditorVideoAspectRatio = '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9';
+
+export type EditorVideoGenerationInput = {
+  prompt: string;
+  model: EditorVideoModel;
+  aspectRatio: EditorVideoAspectRatio;
+  durationSeconds: number;
+  resolution: EditorVideoResolution;
+  mode: 'std';
+  sound: EditorVideoSoundMode;
+  webSearchEnabled?: boolean;
+  priceMudPoints: number;
+  referenceImageSrcs?: string[];
+  referenceVideoSrcs?: string[];
+  referenceAudioSrcs?: string[];
+};
+
+export type EditorVideoGenerationResult = {
+  videoSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: 'generated';
+  prompt: string;
+  actualPrompt?: string | null;
+  model: string;
+  provider: string;
+  taskId: string;
+  priceMudPoints?: number;
+};
+
+export type EditorSoundEffectGenerationInput = {
+  prompt: string;
+  model: 'audio1.0';
+  duration: number;
+  priceMudPoints: number;
+};
+
+export type EditorBackgroundMusicGenerationInput = {
+  gptDescriptionPrompt: string;
+  makeInstrumental: true;
+  priceMudPoints: number;
+};
+
+export type EditorAudioGenerationResult = {
+  audioSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: 'generated';
+  prompt: string;
+  actualPrompt?: string | null;
+  model: string;
+  provider: string;
+  taskId: string;
+  priceMudPoints: number;
+  audioKind: 'sound-effect' | 'background-music';
+  durationSeconds?: number | null;
+};
+
+export type EditorProjectSnapshot = {
+  projectId: string;
+  title: string;
+  canvas?: EditorCanvasSnapshot;
+  viewport: EditorCanvasViewport;
+  layers: EditorProjectLayerSnapshot[];
+  resources: EditorProjectResourceSnapshot[];
+  updatedAt: string;
+};
+
+export type EditorCanvasSnapshot = {
+  canvasId: string;
+  projectId: string;
+  title: string;
+  viewport: EditorCanvasViewport;
+  layers: EditorProjectLayerSnapshot[];
+  createdAt?: string;
+  updatedAt: string;
+};
+
+export type EditorProjectCreateInput = {
+  title?: string;
+};
+
+export type EditorProjectLayoutSaveInput = {
+  viewport: EditorCanvasViewport;
+  layers: EditorProjectLayerSnapshot[];
+};
+
+export type EditorProjectResourceCreateInput = {
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: EditorProjectResourceSourceType;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  durationSeconds?: number | null;
+  sourceResourceId?: string | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+};
+
+export type EditorAssetCreateInput = {
+  folderId: string;
+  label: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  width: number;
+  height: number;
+  sourceType: EditorProjectResourceSourceType;
+  prompt?: string | null;
+  actualPrompt?: string | null;
+  model?: string | null;
+  provider?: string | null;
+  taskId?: string | null;
+  durationSeconds?: number | null;
+  assetKind?: string | null;
+  generationInputs?: EditorAssetGenerationInputs | null;
+};
+
+export type EditorAssetUpdateInput = {
+  label?: string;
+  folderId?: string;
+};
+
+type EditorProjectResponse = {
+  project: EditorProjectSnapshot;
+};
+
+type EditorProjectRecentResponse = {
+  project: EditorProjectSnapshot | null;
+};
+
+type EditorProjectResourceResponse = {
+  resource: EditorProjectResourceSnapshot;
+};
+
+type EditorAssetLibraryResponse = {
+  library: EditorAssetLibrarySnapshot;
+};
+
+type EditorAssetFolderResponse = {
+  folder: EditorAssetFolderSnapshot;
+};
+
+type EditorAssetFolderDeleteResponse = {
+  library: EditorAssetLibrarySnapshot;
+};
+
+type EditorAssetResponse = {
+  asset: EditorAssetSnapshot;
+};
+
+type EditorImageGenerationResponse = EditorImageGenerationResult;
+type EditorIconSpritesheetGenerationResponse =
+  EditorIconSpritesheetGenerationResult;
+type EditorVideoGenerationResponse = EditorVideoGenerationResult;
+type EditorAudioGenerationResponse = EditorAudioGenerationResult;
+
+function jsonRequest(method: 'POST' | 'PATCH', body: Record<string, unknown>) {
+  return {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  };
+}
+
+export async function listEditorProjects() {
+  const response = await requestJson<{ projects: EditorProjectSnapshot[] }>(
+    EDITOR_PROJECT_API_BASE,
+    { method: 'GET' },
+    '读取图片画布工程列表失败',
+  );
+  return response.projects;
+}
+
+export async function loadRecentEditorProject() {
+  return requestJson<EditorProjectRecentResponse>(
+    `${EDITOR_PROJECT_API_BASE}/recent`,
+    { method: 'GET' },
+    '读取图片画布工程失败',
+  );
+}
+
+export async function createEditorProject(
+  input: EditorProjectCreateInput = {},
+) {
+  const response = await requestJson<EditorProjectResponse>(
+    EDITOR_PROJECT_API_BASE,
+    jsonRequest('POST', {
+      title: input.title?.trim() || DEFAULT_PROJECT_TITLE,
+    }),
+    '创建图片画布工程失败',
+  );
+  return response.project;
+}
+
+export async function loadOrCreateRecentEditorProject() {
+  const response = await loadRecentEditorProject();
+  if (response.project) {
+    return response.project;
+  }
+  return createEditorProject({ title: DEFAULT_PROJECT_TITLE });
+}
+
+export async function loadEditorProject(projectId: string) {
+  const response = await requestJson<EditorProjectResponse>(
+    `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}`,
+    { method: 'GET' },
+    '读取图片画布工程失败',
+  );
+  return response.project;
+}
+
+export async function renameEditorProject(projectId: string, title: string) {
+  const response = await requestJson<EditorProjectResponse>(
+    `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}/metadata`,
+    jsonRequest('PATCH', { title }),
+    '重命名图片画布工程失败',
+  );
+  return response.project;
+}
+
+export async function deleteEditorProject(projectId: string) {
+  const response = await requestJson<{ deletedProjectId: string }>(
+    `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}`,
+    { method: 'DELETE' },
+    '删除图片画布工程失败',
+  );
+  return response.deletedProjectId;
+}
+
+export async function saveEditorProjectLayout(
+  projectId: string,
+  input: EditorProjectLayoutSaveInput,
+) {
+  const response = await requestJson<EditorProjectResponse>(
+    `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}`,
+    jsonRequest('PATCH', {
+      viewport: input.viewport,
+      layers: input.layers,
+    }),
+    '保存图片画布工程失败',
+  );
+  return response.project;
+}
+
+export async function createEditorProjectResource(
+  projectId: string,
+  input: EditorProjectResourceCreateInput,
+) {
+  const response = await requestJson<EditorProjectResourceResponse>(
+    `${EDITOR_PROJECT_API_BASE}/${encodeURIComponent(projectId)}/resources`,
+    jsonRequest('POST', { ...input }),
+    '创建图片画布资源失败',
+  );
+  return response.resource;
+}
+
+export async function loadEditorAssetLibrary() {
+  const response = await requestJson<EditorAssetLibraryResponse>(
+    `${EDITOR_ASSET_API_BASE}/library`,
+    { method: 'GET' },
+    '读取图片画布素材库失败',
+  );
+  return response.library;
+}
+
+export async function createEditorAssetFolder(
+  label: string,
+  sortOrder?: number,
+) {
+  const response = await requestJson<EditorAssetFolderResponse>(
+    `${EDITOR_ASSET_API_BASE}/folders`,
+    jsonRequest('POST', { label, sortOrder }),
+    '创建图片画布素材文件夹失败',
+  );
+  return response.folder;
+}
+
+export async function updateEditorAssetFolder(
+  folderId: string,
+  input: { label?: string; collapsed?: boolean },
+) {
+  const response = await requestJson<EditorAssetFolderResponse>(
+    `${EDITOR_ASSET_API_BASE}/folders/${encodeURIComponent(folderId)}`,
+    jsonRequest('PATCH', input),
+    '更新图片画布素材文件夹失败',
+  );
+  return response.folder;
+}
+
+export async function deleteEditorAssetFolder(folderId: string) {
+  const response = await requestJson<EditorAssetFolderDeleteResponse>(
+    `${EDITOR_ASSET_API_BASE}/folders/${encodeURIComponent(folderId)}`,
+    { method: 'DELETE' },
+    '删除图片画布素材文件夹失败',
+  );
+  return response.library;
+}
+
+export async function createEditorAsset(input: EditorAssetCreateInput) {
+  const response = await requestJson<EditorAssetResponse>(
+    EDITOR_ASSET_API_BASE,
+    jsonRequest('POST', input),
+    '创建图片画布素材失败',
+  );
+  return response.asset;
+}
+
+export async function updateEditorAsset(
+  assetId: string,
+  input: EditorAssetUpdateInput,
+) {
+  const response = await requestJson<EditorAssetResponse>(
+    `${EDITOR_ASSET_API_BASE}/${encodeURIComponent(assetId)}`,
+    jsonRequest('PATCH', input),
+    '更新图片画布素材失败',
+  );
+  return response.asset;
+}
+
+export async function deleteEditorAsset(assetId: string) {
+  const response = await requestJson<EditorAssetResponse>(
+    `${EDITOR_ASSET_API_BASE}/${encodeURIComponent(assetId)}`,
+    { method: 'DELETE' },
+    '删除图片画布素材失败',
+  );
+  return response.asset;
+}
+
+export async function generateEditorImage(input: EditorImageGenerationInput) {
+  return requestJson<EditorImageGenerationResponse>(
+    EDITOR_IMAGE_GENERATION_API,
+    jsonRequest('POST', {
+      prompt: input.prompt,
+      ...(input.size ? { size: input.size } : {}),
+      ...(input.kind ? { kind: input.kind } : {}),
+      ...(input.model ? { model: input.model } : {}),
+      ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
+      ...(input.imageSize ? { imageSize: input.imageSize } : {}),
+      ...(input.referenceImageSrcs?.length
+        ? { referenceImageSrcs: input.referenceImageSrcs }
+        : {}),
+      ...(input.projectId ? { projectId: input.projectId } : {}),
+      ...(input.assetKind ? { assetKind: input.assetKind } : {}),
+      ...(input.generationInputs
+        ? { generationInputs: input.generationInputs }
+        : {}),
+      ...(input.assetFolderId ? { assetFolderId: input.assetFolderId } : {}),
+      ...(input.assetLabel ? { assetLabel: input.assetLabel } : {}),
+      ...(input.sourceResourceId
+        ? { sourceResourceId: input.sourceResourceId }
+        : {}),
+      ...(input.canvasCompletion
+        ? { canvasCompletion: input.canvasCompletion }
+        : {}),
+    }),
+    '生成图片失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function generateEditorIconSpritesheet(
+  input: EditorIconSpritesheetGenerationInput,
+) {
+  return requestJson<EditorIconSpritesheetGenerationResponse>(
+    EDITOR_ICON_SPRITESHEET_GENERATION_API,
+    jsonRequest('POST', {
+      referenceImageSrc: input.referenceImageSrc,
+      iconDescriptions: input.iconDescriptions,
+      model: input.model?.trim() || EDITOR_IMAGE_MODEL_NANOBANANA2,
+      ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
+      ...(input.imageSize ? { imageSize: input.imageSize } : {}),
+      priceMudPoints: input.priceMudPoints,
+      ...(input.projectId ? { projectId: input.projectId } : {}),
+      ...(input.generationInputs
+        ? { generationInputs: input.generationInputs }
+        : {}),
+      ...(input.assetFolderId ? { assetFolderId: input.assetFolderId } : {}),
+    }),
+    '生成图标素材失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function extractEditorUiDesignAssets(
+  input: EditorUiDesignAssetExtractionInput,
+) {
+  return requestJson<EditorIconSpritesheetGenerationResponse>(
+    EDITOR_UI_DESIGN_ASSET_EXTRACTION_API,
+    jsonRequest('POST', {
+      sourceImageSrc: input.sourceImageSrc,
+      ...(input.projectId ? { projectId: input.projectId } : {}),
+      ...(input.generationInputs
+        ? { generationInputs: input.generationInputs }
+        : {}),
+      ...(input.assetFolderId ? { assetFolderId: input.assetFolderId } : {}),
+      ...(input.spritesheetLabel
+        ? { spritesheetLabel: input.spritesheetLabel }
+        : {}),
+    }),
+    '提取UI设计图素材失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function editEditorImage(input: EditorImageEditInput) {
+  return requestJson<EditorImageGenerationResponse>(
+    EDITOR_IMAGE_EDIT_API,
+    jsonRequest('POST', {
+      prompt: input.prompt,
+      sourceImageSrc: input.sourceImageSrc,
+      ...(input.size ? { size: input.size } : {}),
+      ...(input.model ? { model: input.model } : {}),
+      ...(input.projectId ? { projectId: input.projectId } : {}),
+      ...(input.assetKind ? { assetKind: input.assetKind } : {}),
+      ...(input.generationInputs
+        ? { generationInputs: input.generationInputs }
+        : {}),
+      ...(input.assetFolderId ? { assetFolderId: input.assetFolderId } : {}),
+      ...(input.assetLabel ? { assetLabel: input.assetLabel } : {}),
+      ...(input.sourceResourceId
+        ? { sourceResourceId: input.sourceResourceId }
+        : {}),
+    }),
+    '修改图片失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function generateEditorCharacterAnimation(
+  input: EditorCharacterAnimationGenerationInput,
+) {
+  return requestJson<EditorCharacterAnimationGenerationResult>(
+    EDITOR_CHARACTER_ANIMATION_GENERATION_API,
+    jsonRequest('POST', input),
+    '生成角色动画失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function generateEditorVideo(input: EditorVideoGenerationInput) {
+  return requestJson<EditorVideoGenerationResponse>(
+    EDITOR_VIDEO_GENERATION_API,
+    jsonRequest('POST', {
+      prompt: input.prompt,
+      model: input.model,
+      aspectRatio: input.aspectRatio,
+      durationSeconds: input.durationSeconds,
+      resolution: input.resolution,
+      mode: input.mode,
+      sound: input.sound,
+      webSearchEnabled: input.webSearchEnabled ?? true,
+      priceMudPoints: input.priceMudPoints,
+      ...(input.referenceImageSrcs?.length
+        ? { referenceImageSrcs: input.referenceImageSrcs }
+        : {}),
+      ...(input.referenceVideoSrcs?.length
+        ? { referenceVideoSrcs: input.referenceVideoSrcs }
+        : {}),
+      ...(input.referenceAudioSrcs?.length
+        ? { referenceAudioSrcs: input.referenceAudioSrcs }
+        : {}),
+    }),
+    '生成视频失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function generateEditorSoundEffect(
+  input: EditorSoundEffectGenerationInput,
+) {
+  return requestJson<EditorAudioGenerationResponse>(
+    EDITOR_SOUND_EFFECT_GENERATION_API,
+    jsonRequest('POST', {
+      prompt: input.prompt,
+      model: input.model,
+      duration: input.duration,
+      priceMudPoints: input.priceMudPoints,
+    }),
+    '生成游戏音效失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
+
+export async function generateEditorBackgroundMusic(
+  input: EditorBackgroundMusicGenerationInput,
+) {
+  return requestJson<EditorAudioGenerationResponse>(
+    EDITOR_BACKGROUND_MUSIC_GENERATION_API,
+    jsonRequest('POST', {
+      gptDescriptionPrompt: input.gptDescriptionPrompt,
+      makeInstrumental: input.makeInstrumental,
+      priceMudPoints: input.priceMudPoints,
+    }),
+    '生成游戏背景音乐失败',
+    {
+      timeoutMs: 1_200_000,
+      retry: {
+        maxRetries: 0,
+      },
+    },
+  );
+}
diff --git a/src/services/image-editor/editorReferenceUploadClient.test.ts b/src/services/image-editor/editorReferenceUploadClient.test.ts
new file mode 100644
index 000000000..dbefbcd1f
--- /dev/null
+++ b/src/services/image-editor/editorReferenceUploadClient.test.ts
@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { requestJson } from '../apiClient';
+import { getSignedAssetReadUrl } from '../assetReadUrlService';
+import { uploadEditorSeedanceReferenceFile } from './editorReferenceUploadClient';
+
+vi.mock('../apiClient', () => ({
+  requestJson: vi.fn(),
+}));
+
+vi.mock('../assetReadUrlService', () => ({
+  getSignedAssetReadUrl: vi.fn(),
+}));
+
+const requestJsonMock = vi.mocked(requestJson);
+const getSignedAssetReadUrlMock = vi.mocked(getSignedAssetReadUrl);
+
+describe('editorReferenceUploadClient', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(Date, 'now').mockReturnValue(1771400000000);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(null, { status: 200 })),
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('uploads Seedance reference videos through direct OSS upload and returns object metadata', async () => {
+    requestJsonMock
+      .mockResolvedValueOnce({
+        upload: {
+          bucket: 'bucket',
+          host: 'https://oss.example.com',
+          objectKey:
+            'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+          legacyPublicPath:
+            '/generated-character-drafts/editor/seedance-references/video/ref.mp4',
+          formFields: {
+            key: 'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+            policy: 'policy',
+            'x-oss-signature': 'signature',
+          },
+        },
+      })
+      .mockResolvedValueOnce({
+        assetObject: {
+          assetObjectId: 'assetobj-video',
+          objectKey:
+            'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+          assetKind: 'editor_seedance_reference_video',
+        },
+      });
+    getSignedAssetReadUrlMock.mockResolvedValueOnce(
+      'https://signed.example.com/ref.mp4',
+    );
+
+    const result = await uploadEditorSeedanceReferenceFile(
+      new File(['video'], 'ref.mp4', { type: 'video/mp4' }),
+      'video',
+    );
+
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/assets/direct-upload-tickets',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: expect.any(String),
+      }),
+      '创建参考素材上传凭证失败',
+    );
+    const ticketBody = JSON.parse(
+      (requestJsonMock.mock.calls[0]?.[1] as RequestInit).body as string,
+    );
+    expect(ticketBody).toMatchObject({
+      legacyPrefix: 'generated-character-drafts',
+      pathSegments: [
+        'editor',
+        'seedance-references',
+        'video',
+        '1771400000000',
+      ],
+      fileName: 'ref.mp4',
+      contentType: 'video/mp4',
+      access: 'private',
+      maxSizeBytes: 5,
+      successActionStatus: 200,
+      metadata: {
+        asset_kind: 'editor_seedance_reference_video',
+        editor_seedance_reference_type: 'video',
+      },
+    });
+    expect(fetch).toHaveBeenCalledWith(
+      'https://oss.example.com',
+      expect.objectContaining({
+        method: 'POST',
+        body: expect.any(FormData),
+      }),
+    );
+    expect(requestJsonMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/assets/objects/confirm',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: expect.any(String),
+      }),
+      '确认参考素材资产失败',
+    );
+    const confirmBody = JSON.parse(
+      (requestJsonMock.mock.calls[1]?.[1] as RequestInit).body as string,
+    );
+    expect(confirmBody).toMatchObject({
+      bucket: 'bucket',
+      objectKey: 'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+      contentType: 'video/mp4',
+      contentLength: 5,
+      assetKind: 'editor_seedance_reference_video',
+      accessPolicy: 'private',
+      entityId: 'editor-seedance-reference-video',
+    });
+    expect(getSignedAssetReadUrlMock).toHaveBeenCalledWith(
+      {
+        objectKey:
+          'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+        expireSeconds: 3600,
+      },
+      undefined,
+      { bypassCache: true },
+    );
+    expect(result).toEqual({
+      src: 'https://signed.example.com/ref.mp4',
+      objectKey:
+        'generated-character-drafts/editor/seedance-references/video/ref.mp4',
+      assetObjectId: 'assetobj-video',
+      legacyPublicPath:
+        '/generated-character-drafts/editor/seedance-references/video/ref.mp4',
+    });
+  });
+});
diff --git a/src/services/image-editor/editorReferenceUploadClient.ts b/src/services/image-editor/editorReferenceUploadClient.ts
new file mode 100644
index 000000000..d9a8bace8
--- /dev/null
+++ b/src/services/image-editor/editorReferenceUploadClient.ts
@@ -0,0 +1,139 @@
+import { requestJson } from '../apiClient';
+import { getSignedAssetReadUrl } from '../assetReadUrlService';
+
+type EditorSeedanceReferenceMediaType = 'video' | 'audio';
+
+type DirectUploadTicketResponse = {
+  upload: {
+    bucket: string;
+    host: string;
+    objectKey: string;
+    legacyPublicPath: string;
+    formFields: Record<string, string | null | undefined>;
+  };
+};
+
+type ConfirmAssetObjectResponse = {
+  assetObject: {
+    assetObjectId: string;
+    objectKey: string;
+    assetKind: string;
+  };
+};
+
+export type UploadedEditorSeedanceReference = {
+  src: string;
+  objectKey: string;
+  assetObjectId: string;
+  legacyPublicPath: string;
+};
+
+const EDITOR_SEEDANCE_REFERENCE_READ_EXPIRE_SECONDS = 60 * 60;
+
+function resolveReferenceAssetKind(mediaType: EditorSeedanceReferenceMediaType) {
+  return mediaType === 'video'
+    ? 'editor_seedance_reference_video'
+    : 'editor_seedance_reference_audio';
+}
+
+function resolveReferenceEntityId(mediaType: EditorSeedanceReferenceMediaType) {
+  return `editor-seedance-reference-${mediaType}`;
+}
+
+function sanitizeReferenceFileName(fileName: string, mediaType: EditorSeedanceReferenceMediaType) {
+  const trimmedName = fileName.trim();
+  if (trimmedName) {
+    return trimmedName;
+  }
+  return mediaType === 'video' ? 'seedance-reference.mp4' : 'seedance-reference.mp3';
+}
+
+async function postDirectUploadFile(
+  upload: DirectUploadTicketResponse['upload'],
+  file: File,
+) {
+  const formData = new FormData();
+  Object.entries(upload.formFields).forEach(([key, value]) => {
+    if (value !== null && value !== undefined) {
+      formData.append(key, value);
+    }
+  });
+  formData.append('file', file, file.name);
+
+  const response = await fetch(upload.host, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!response.ok) {
+    throw new Error('上传参考素材失败');
+  }
+}
+
+export async function uploadEditorSeedanceReferenceFile(
+  file: File,
+  mediaType: EditorSeedanceReferenceMediaType,
+): Promise<UploadedEditorSeedanceReference> {
+  const assetKind = resolveReferenceAssetKind(mediaType);
+  const fileName = sanitizeReferenceFileName(file.name, mediaType);
+  const contentType = file.type.trim() || 'application/octet-stream';
+
+  const ticket = await requestJson<DirectUploadTicketResponse>(
+    '/api/assets/direct-upload-tickets',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        legacyPrefix: 'generated-character-drafts',
+        pathSegments: ['editor', 'seedance-references', mediaType, `${Date.now()}`],
+        fileName,
+        contentType,
+        access: 'private',
+        maxSizeBytes: file.size,
+        successActionStatus: 200,
+        metadata: {
+          asset_kind: assetKind,
+          editor_seedance_reference_type: mediaType,
+        },
+      }),
+    },
+    '创建参考素材上传凭证失败',
+  );
+
+  await postDirectUploadFile(ticket.upload, file);
+
+  const confirmed = await requestJson<ConfirmAssetObjectResponse>(
+    '/api/assets/objects/confirm',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bucket: ticket.upload.bucket,
+        objectKey: ticket.upload.objectKey,
+        contentType,
+        contentLength: file.size,
+        assetKind,
+        accessPolicy: 'private',
+        entityId: resolveReferenceEntityId(mediaType),
+      }),
+    },
+    '确认参考素材资产失败',
+  );
+
+  // 中文注释：返回短期 signed URL 供前端立即预览；生成请求最终优先提交 objectKey，由后端统一重新签名。
+  const signedUrl = await getSignedAssetReadUrl(
+    {
+      objectKey: confirmed.assetObject.objectKey,
+      expireSeconds: EDITOR_SEEDANCE_REFERENCE_READ_EXPIRE_SECONDS,
+    },
+    undefined,
+    { bypassCache: true },
+  );
+
+  return {
+    src: signedUrl,
+    objectKey: confirmed.assetObject.objectKey,
+    assetObjectId: confirmed.assetObject.assetObjectId,
+    legacyPublicPath: ticket.upload.legacyPublicPath,
+  };
+}
diff --git a/src/services/rpg-entry/rpgProfileClient.test.ts b/src/services/rpg-entry/rpgProfileClient.test.ts
index 68d292b21..5b46128fe 100644
--- a/src/services/rpg-entry/rpgProfileClient.test.ts
+++ b/src/services/rpg-entry/rpgProfileClient.test.ts
@@ -7,8 +7,11 @@ const { fetchWithApiAuthMock, requestJsonMock } = vi.hoisted(() => ({
 
 import {
   clearRpgProfileBrowseHistory,
+  createRpgProfileExternalApiKey,
   listRpgProfileBrowseHistory,
+  listRpgProfileExternalApiKeys,
   listRpgProfileSaveArchives,
+  revokeRpgProfileExternalApiKey,
   resumeRpgProfileSaveArchive,
   submitRpgProfileFeedback,
   syncRpgProfileBrowseHistory,
@@ -199,6 +202,64 @@ describe('rpgProfileClient save archive routes', () => {
   });
 });
 
+describe('rpgProfileClient external api key routes', () => {
+  beforeEach(() => {
+    requestJsonMock.mockReset();
+    requestJsonMock.mockResolvedValue({ keys: [] });
+  });
+
+  it('lists profile api keys from the profile route', async () => {
+    await listRpgProfileExternalApiKeys();
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/profile/api-keys',
+      expect.objectContaining({ method: 'GET' }),
+      '读取 API Key 失败',
+      expect.objectContaining({
+        retry: expect.objectContaining({ maxRetries: 1 }),
+      }),
+    );
+  });
+
+  it('creates profile api keys through the profile route', async () => {
+    await createRpgProfileExternalApiKey('测试 Key');
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/profile/api-keys',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      }),
+      '创建 API Key 失败',
+      expect.objectContaining({
+        retry: expect.objectContaining({
+          maxRetries: 1,
+          retryUnsafeMethods: true,
+        }),
+      }),
+    );
+    expect(JSON.parse(requestJsonMock.mock.calls[0][1].body)).toEqual({
+      name: '测试 Key',
+    });
+  });
+
+  it('revokes profile api keys through the profile route', async () => {
+    await revokeRpgProfileExternalApiKey('key:1');
+
+    expect(requestJsonMock).toHaveBeenCalledWith(
+      '/api/profile/api-keys/key%3A1',
+      expect.objectContaining({ method: 'DELETE' }),
+      '撤销 API Key 失败',
+      expect.objectContaining({
+        retry: expect.objectContaining({
+          maxRetries: 1,
+          retryUnsafeMethods: true,
+        }),
+      }),
+    );
+  });
+});
+
 describe('rpgProfileClient feedback routes', () => {
   beforeEach(() => {
     requestJsonMock.mockReset();
diff --git a/src/services/rpg-entry/rpgProfileClient.ts b/src/services/rpg-entry/rpgProfileClient.ts
index 8aab97bc9..53f3facad 100644
--- a/src/services/rpg-entry/rpgProfileClient.ts
+++ b/src/services/rpg-entry/rpgProfileClient.ts
@@ -2,6 +2,9 @@ import type {
   ClaimProfileTaskRewardResponse,
   ConfirmWechatProfileRechargeOrderResponse,
   CreateProfileRechargeOrderResponse,
+  ExternalApiKeyCreateResponse,
+  ExternalApiKeyListResponse,
+  ExternalApiKeyMutationResponse,
   PlatformBrowseHistoryBatchSyncRequest,
   PlatformBrowseHistoryResponse,
   PlatformBrowseHistoryWriteEntry,
@@ -79,6 +82,45 @@ export function getRpgProfileWalletLedger(options: RuntimeRequestOptions = {}) {
   );
 }
 
+export function listRpgProfileExternalApiKeys(
+  options: RuntimeRequestOptions = {},
+) {
+  return requestRpgRuntimeJson<ExternalApiKeyListResponse>(
+    '/profile/api-keys',
+    { method: 'GET' },
+    '读取 API Key 失败',
+    options,
+  );
+}
+
+export function createRpgProfileExternalApiKey(
+  name: string,
+  options: RuntimeRequestOptions = {},
+) {
+  return requestRpgRuntimeJson<ExternalApiKeyCreateResponse>(
+    '/profile/api-keys',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name }),
+    },
+    '创建 API Key 失败',
+    options,
+  );
+}
+
+export function revokeRpgProfileExternalApiKey(
+  keyId: string,
+  options: RuntimeRequestOptions = {},
+) {
+  return requestRpgRuntimeJson<ExternalApiKeyMutationResponse>(
+    `/profile/api-keys/${encodeURIComponent(keyId)}`,
+    { method: 'DELETE' },
+    '撤销 API Key 失败',
+    options,
+  );
+}
+
 export function getRpgProfileRechargeCenter(
   options: RuntimeRequestOptions = {},
 ) {