Merge branch 'codex/editor-asset-library' of https://git.genarrative.world/GenarrativeAI/Genarrative into codex/editor-asset-library

TRACKING.md

@@ -139,3 +139,6 @@
 - 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-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`。

docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md

@@ -199,14 +199,42 @@
   - 该模块用独立单测覆盖生成结果优先锚定、生成中 / 手动关闭隐藏输入框、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`
+  - 承载舞台派生状态和右键菜单模型：选中图层、生成对象锚点、生成输入框位置、选中浮动工具栏位置、图片菜单图层、右键菜单目标图层，以及显示 / 解锁菜单文案判断。
+  - 该模型复用既有图层命令模型与浮层定位模型，不重新实现坐标公式，避免拆分后出现第二套右键目标和浮层定位规则。
+  - 新增单测覆盖生成锚定、选中工具栏位置、右键目标集合、显示 / 解锁判断和菜单位置限制。
+
+- `useImageCanvasStageController.ts`
+  - 承载舞台控制胶水：清空画布焦点、空白画布右键菜单和图层右键菜单处理。
+  - 主视图继续保留工具切换、上传 / 生成入口、图层命令、项目持久化和舞台 pointer 状态机，避免把跨工作流动作塞进单个 hook。
+  - 本阶段主视图从 1086 行降至 993 行；后续若继续拆分，应优先考虑顶栏 / 项目标题区域或把侧栏图层右键入口并入同一舞台菜单控制层。
+
+## 第二十六阶段模块
+
+- `ImageCanvasTopbarView.tsx`
+  - 承载编辑器顶部栏视觉结构：返回项目入口、项目标题展示、项目标题重命名表单、下载画布素材按钮和导出状态提示。
+  - 主视图继续保留项目标题 / 重命名状态所属的 chrome hook、项目持久化、导出工作流和实际导出副作用；顶栏只负责表单事件和显示，不接管业务状态。
+  - 新增组件单测覆盖返回入口、标题编辑入口、重命名提交 / 取消、导出按钮禁用 / 启用和导出状态提示。
+  - 本阶段主视图从 993 行降至 905 行；后续可继续评估隐藏上传 input / 侧栏拖拽预览这类根级浮层是否值得抽为编辑器 shell 视图。
+
 ## 后续阶段
 
 - 后续可继续选择更高内聚的交互 workflow 或持久化边界，不再把生成链路继续拆成浅层 wrapper。
-- 右键菜单定位、工程资源持久化、舞台派生状态和历史捕获仍在主视图编排，拆分前需要先确认不会破坏多生成对象同时存在、完成时读取最新占位框、素材拖拽上传位置和角色动画优先传 `objectKey` 的历史保护规则。
+- 工程资源持久化、工具切换和历史捕获仍在主视图编排，拆分前需要先确认不会破坏多生成对象同时存在、完成时读取最新占位框、素材拖拽上传位置和角色动画优先传 `objectKey` 的历史保护规则。
 
 ## 验证计划
 
-- `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/ImageCanvasEditorView.test.tsx src/components/auth/PlatformAuthModalShell.test.tsx src/components/auth/AuthGate.test.tsx`
+- `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`

src/components/image-editor/ImageCanvasEditorView.tsx

@@ -1,44 +1,17 @@
-import { Check, ChevronLeft, Download, Pencil, X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import {
-  type MouseEvent as ReactMouseEvent,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
 
-import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
-import { PlatformTextField } from '../common/PlatformTextField';
 import { useAuthUi } from '../auth/AuthUiContext';
-import { EditorIconButton } from './ImageCanvasEditorPrimitives';
 import { ImageCanvasGenerationComposerView } from './ImageCanvasGenerationComposerView';
 import { ImageCanvasMetadataModalView } from './ImageCanvasMetadataModalView';
-import {
-  getCanvasLayersByIds,
-  resolveContextTargetLayerIds,
-} from './ImageCanvasLayerCommandModel';
 import { ImageCanvasSidebarView } from './ImageCanvasSidebarView';
 import { ImageCanvasStageView } from './ImageCanvasStageView';
-import {
+import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
-  createLayerFromAsset,
+import { resolveContextMenuPosition } from './ImageCanvasEditorModel';
-  isGeneratedLayer,
-  isLayerLinkedToAsset,
-  resolveContextMenuPosition,
-} from './ImageCanvasEditorModel';
-import {
-  getGenerationFrameAriaLabel,
-  getGenerationFrameLabel,
-  getLayerKindLabel,
-} from './ImageCanvasGenerationModel';
 import {
   isCanvasGenerationComposerVisible,
   resolveCharacterAnimationPanelStyle,
-  resolveGenerationAnchor,
-  resolveGenerationComposerStyle,
   resolveIconComposerStyle,
   resolveQuickEditPanelStyle,
-  resolveSelectedToolbarStyle,
 } from './ImageCanvasOverlayModel';
 import type {
   AssetPointerDragState,
@@ -46,20 +19,22 @@ import type {
   CanvasLayer,
   CanvasTool,
   CanvasViewport,
-  EditorAsset,
   ImageContextMenuState,
 } from './ImageCanvasEditorTypes';
 import { useCanvasHistory } from './useCanvasHistory';
 import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
 import { useImageCanvasAssetLibrary } from './useImageCanvasAssetLibrary';
+import {
+  useImageCanvasAssetCanvasBridge,
+  useImageCanvasAssetLayerCleanup,
+} from './useImageCanvasAssetCanvasBridge';
 import { useImageCanvasAssetExportWorkflow } from './useImageCanvasAssetExportWorkflow';
-import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
-import { useImageCanvasCanvasDropWorkflow } from './useImageCanvasCanvasDropWorkflow';
 import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
 import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
 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 {
@@ -179,41 +154,12 @@ export function ImageCanvasEditorView() {
     toggleBackgroundSettings,
     toggleMinimap,
   } = useImageCanvasEditorChrome({ openEditorLoginModal });
-  const removeCanvasLayersLinkedToAssets = useCallback(
+  const removeCanvasLayersLinkedToAssets = useImageCanvasAssetLayerCleanup({
-    (deletedAssets: EditorAsset[]) => {
+    layers,
-      if (!deletedAssets.length) {
+    setLayers,
-        return;
+    setSelectedLayerId,
-      }
+    setSelectedLayerIds,
-      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],
-  );
   const {
     assetFolders,
     setAssetFolders,
@@ -288,54 +234,6 @@ export function ImageCanvasEditorView() {
   } = useCanvasGenerationDialogs({
     onActivate: handleActivateCanvasGenerationDialog,
   });
-  const selectedLayer = useMemo(
-    () => layers.find((layer) => layer.id === selectedLayerId) ?? null,
-    [layers, selectedLayerId],
-  );
-  const selectedLayerCount = selectedLayerIds.length;
-  const hasMultipleSelectedLayers = selectedLayerCount > 1;
-  const activeGenerationLayer = useMemo(
-    () =>
-      activeCanvasGenerationDialog?.generatedLayerId
-        ? (layers.find(
-            (layer) =>
-              layer.id === activeCanvasGenerationDialog.generatedLayerId,
-          ) ?? null)
-        : null,
-    [activeCanvasGenerationDialog, layers],
-  );
-  const generationAnchor = activeCanvasGenerationDialog
-    ? resolveGenerationAnchor({
-        dialog: activeCanvasGenerationDialog,
-        generatedLayer: activeGenerationLayer,
-      })
-    : null;
-  const generationComposerStyle = resolveGenerationComposerStyle({
-    dialog: activeCanvasGenerationDialog,
-    anchor: generationAnchor,
-    viewport,
-  });
-  const selectedToolbarStyle = resolveSelectedToolbarStyle({
-    selectedLayer,
-    viewport,
-    canvasSize,
-  });
-  const imageContextMenuLayer = imageContextMenu
-    ? (layers.find((layer) => layer.id === imageContextMenu.layerId) ?? null)
-    : null;
-  const getContextTargetLayerIds = useCallback(
-    (menu: CanvasContextMenuState | null = contextMenu) =>
-      resolveContextTargetLayerIds(menu, selectedLayerIdsRef.current),
-    [contextMenu],
-  );
-  const contextTargetIds = getContextTargetLayerIds(contextMenu);
-  const contextTargetLayers = getCanvasLayersByIds(layers, contextTargetIds);
-  const contextShouldShowLayer = contextTargetLayers.some(
-    (layer) => layer.hidden,
-  );
-  const contextShouldUnlockLayer = contextTargetLayers.some(
-    (layer) => layer.locked,
-  );
   const canvasHistoryRefs = useMemo(
     () => ({
       layersRef,
@@ -500,6 +398,31 @@ export function ImageCanvasEditorView() {
     closeGenerateComposer,
     clearDeletedLayerGenerationState,
   } = generationWorkflow;
+  const {
+    selectedLayer,
+    generationComposerStyle,
+    selectedToolbarStyle,
+    imageContextMenuLayer,
+    contextShouldShowLayer,
+    contextShouldUnlockLayer,
+    clearCanvasFocus,
+    handleCanvasContextMenu,
+    handleLayerContextMenu,
+  } = useImageCanvasStageController({
+    layers,
+    selectedLayerId,
+    selectedLayerIds,
+    activeCanvasGenerationDialog,
+    imageContextMenu,
+    setImageContextMenu,
+    contextMenu,
+    setContextMenu,
+    viewport,
+    canvasSize,
+    selectSingleLayer,
+    hideGeneratedLayerPanelAfterBlur,
+    getCanvasPointFromClient,
+  });
   const iconComposerStyle = resolveIconComposerStyle({
     dialog: activeCanvasGenerationDialog,
     composerStyle: generationComposerStyle,
@@ -577,13 +500,6 @@ export function ImageCanvasEditorView() {
     appendCanvasLayersWithResources,
     selectSingleLayer,
   });
-
-  const clearCanvasFocus = useCallback(() => {
-    selectSingleLayer(null);
-    hideGeneratedLayerPanelAfterBlur();
-    setImageContextMenu(null);
-    setContextMenu(null);
-  }, [hideGeneratedLayerPanelAfterBlur, selectSingleLayer]);
   const {
     canvasMarquee,
     isPanning,
@@ -675,95 +591,36 @@ export function ImageCanvasEditorView() {
     };
   }, []);
 
-  const addAssetLayer = (
+  const {
-    asset: EditorAsset,
+    addAssetLayer,
-    position?: { x: number; y: number },
+    handleCanvasDragOver,
-  ) => {
+    handleCanvasDragLeave,
-    setActiveUploadFolderId(asset.folderId);
+    handleCanvasDrop,
-    layerCounterRef.current += 1;
+  } = useImageCanvasAssetCanvasBridge({
-    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);
-  };
-
-  useImageCanvasAssetPointerDragBridge({
     assetPointerDragRef,
     suppressAssetClickRef,
     assets,
+    assetFolders,
+    layerCounterRef,
+    viewport,
+    canvasSize,
     resolveAssetFolderId,
     resolveCanvasPoint,
+    getCanvasDropPoint,
     setAssetPointerDrag,
+    setActiveUploadFolderId,
     setUploadDropTarget,
+    setHoveredLayerId,
     updateAssetMoveDropFolder,
     moveAssetToFolder,
-    addAssetLayer,
+    captureCanvasHistory,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    addUploadedFiles,
   });
 
   deleteLayerByIdRef.current = deleteLayerById;
 
-  const { handleCanvasDragOver, handleCanvasDragLeave, handleCanvasDrop } =
-    useImageCanvasCanvasDropWorkflow({
-      assets,
-      assetFolders,
-      setUploadDropTarget,
-      updateAssetMoveDropFolder,
-      getCanvasDropPoint,
-      addAssetLayer,
-      addUploadedFiles,
-    });
-
-  const handleCanvasContextMenu = (event: ReactMouseEvent<HTMLDivElement>) => {
-    event.preventDefault();
-    event.stopPropagation();
-    const position = resolveContextMenuPosition(
-      event.clientX,
-      event.clientY,
-      'blank',
-    );
-    setImageContextMenu(null);
-    setContextMenu({
-      kind: 'blank',
-      ...position,
-      canvasPoint: getCanvasPointFromClient(event.clientX, event.clientY),
-    });
-  };
-
-  const handleLayerContextMenu = (
-    event: ReactMouseEvent<HTMLButtonElement>,
-    layer: CanvasLayer,
-  ) => {
-    event.preventDefault();
-    event.stopPropagation();
-    if (!selectedLayerIds.includes(layer.id)) {
-      selectSingleLayer(layer.id);
-    }
-    const position = resolveContextMenuPosition(
-      event.clientX,
-      event.clientY,
-      'layer',
-    );
-    setContextMenu({
-      kind: 'layer',
-      layerId: layer.id,
-      ...position,
-      canvasPoint: getCanvasPointFromClient(event.clientX, event.clientY),
-    });
-    setImageContextMenu({
-      layerId: layer.id,
-      ...position,
-    });
-  };
-
   const switchTool = (tool: CanvasTool) => {
     clearActiveInteraction();
     if (tool === 'upload') {
@@ -882,108 +739,23 @@ export function ImageCanvasEditorView() {
       />
 
       <div className="image-canvas-editor__main">
-        <div className="image-canvas-editor__topbar">
+        <ImageCanvasTopbarView
-          <a
+          projectId={projectId}
-            className="image-canvas-editor__project-back-button"
+          projectTitle={projectTitle}
-            href="/project"
+          projectRenameValue={projectRenameValue}
-            aria-label="返回项目页面"
+          isRenamingProject={isRenamingProject}
-            title="返回项目"
+          isProjectRenameSaving={isProjectRenameSaving}
-          >
+          projectRenameError={projectRenameError}
-            <ChevronLeft className="h-4 w-4" aria-hidden="true" />
+          layers={layers}
-          </a>
+          assetExportStatus={assetExportStatus}
-          <div className="image-canvas-editor__title-block">
+          isExportingAssets={isExportingAssets}
-            {isRenamingProject ? (
+          setProjectRenameValue={setProjectRenameValue}
-              <form
+          startProjectRename={startProjectRename}
-                className="image-canvas-editor__project-title-form"
+          cancelProjectRename={cancelProjectRename}
-                onSubmit={(event) => {
+          submitProjectRename={submitProjectRename}
-                  event.preventDefault();
+          resetProjectRenameError={resetProjectRenameError}
-                  submitProjectRename(projectId);
+          exportCanvasAssets={exportCanvasAssets}
-                }}
+        />
-              >
-                <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 ||
-                !layers.some((layer) => layer.src.trim().length > 0)
-              }
-              onClick={() => void exportCanvasAssets()}
-            />
-            {assetExportStatus ? (
-              <PlatformStatusMessage
-                tone={assetExportStatus.tone}
-                surface="platform"
-                size="xs"
-                role={assetExportStatus.tone === 'error' ? 'alert' : 'status'}
-              >
-                {assetExportStatus.message}
-              </PlatformStatusMessage>
-            ) : null}
-          </div>
-        </div>
 
         <ImageCanvasStageView
           canvasViewportRef={canvasViewportRef}

src/components/image-editor/ImageCanvasStageControllerModel.test.ts

@@ -0,0 +1,155 @@
+/* @vitest-environment jsdom */
+
+import { describe, expect, it } from 'vitest';
+
+import type {
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  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,
+  };
+}
+
+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('ImageCanvasStageControllerModel', () => {
+  it('derives selected layer, generation anchor, and overlay positions', () => {
+    const selectedLayer = createLayer({ id: 'selected', x: 40, y: 60 });
+    const generatedLayer = createLayer({
+      id: 'generated',
+      x: 200,
+      y: 160,
+      width: 320,
+      height: 180,
+    });
+    const dialog = createDialog({ generatedLayerId: generatedLayer.id });
+
+    const model = resolveImageCanvasStageControllerModel({
+      layers: [selectedLayer, generatedLayer],
+      selectedLayerId: selectedLayer.id,
+      selectedLayerIds: [selectedLayer.id, generatedLayer.id],
+      activeCanvasGenerationDialog: dialog,
+      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.activeGenerationLayer).toBe(generatedLayer);
+    expect(model.generationAnchor).toBe(generatedLayer);
+    expect(model.generationComposerStyle).toEqual({ left: 730, top: 710 });
+    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],
+      activeCanvasGenerationDialog: null,
+      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,
+      },
+    });
+  });
+});

src/components/image-editor/ImageCanvasStageControllerModel.ts

@@ -0,0 +1,148 @@
+import {
+  getCanvasLayersByIds,
+  resolveContextTargetLayerIds,
+} from './ImageCanvasLayerCommandModel';
+import {
+  resolveContextMenuPosition,
+} from './ImageCanvasEditorModel';
+import type {
+  CanvasContextMenuState,
+  CanvasGenerationDialogState,
+  CanvasLayer,
+  CanvasViewport,
+  ImageContextMenuState,
+} from './ImageCanvasEditorTypes';
+import {
+  resolveGenerationAnchor,
+  resolveGenerationComposerStyle,
+  resolveSelectedToolbarStyle,
+} from './ImageCanvasOverlayModel';
+
+export type ImageCanvasStageControllerModel = {
+  selectedLayer: CanvasLayer | null;
+  selectedLayerCount: number;
+  hasMultipleSelectedLayers: boolean;
+  activeGenerationLayer: CanvasLayer | null;
+  generationAnchor: CanvasLayer | CanvasGenerationDialogState['placeholder'] | null;
+  generationComposerStyle: ReturnType<typeof resolveGenerationComposerStyle>;
+  selectedToolbarStyle: ReturnType<typeof resolveSelectedToolbarStyle>;
+  imageContextMenuLayer: CanvasLayer | null;
+  contextTargetIds: string[];
+  contextTargetLayers: CanvasLayer[];
+  contextShouldShowLayer: boolean;
+  contextShouldUnlockLayer: boolean;
+};
+
+type ResolveImageCanvasStageControllerModelOptions = {
+  layers: CanvasLayer[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  activeCanvasGenerationDialog: CanvasGenerationDialogState | null;
+  imageContextMenu: ImageContextMenuState | null;
+  contextMenu: CanvasContextMenuState | null;
+  viewport: CanvasViewport;
+  canvasSize: { width: number; height: number };
+};
+
+export function resolveImageCanvasStageControllerModel({
+  layers,
+  selectedLayerId,
+  selectedLayerIds,
+  activeCanvasGenerationDialog,
+  imageContextMenu,
+  contextMenu,
+  viewport,
+  canvasSize,
+}: ResolveImageCanvasStageControllerModelOptions): ImageCanvasStageControllerModel {
+  const selectedLayer =
+    layers.find((layer) => layer.id === selectedLayerId) ?? null;
+  const selectedLayerCount = selectedLayerIds.length;
+  const activeGenerationLayer =
+    activeCanvasGenerationDialog?.generatedLayerId
+      ? (layers.find(
+          (layer) => layer.id === activeCanvasGenerationDialog.generatedLayerId,
+        ) ?? null)
+      : null;
+  const generationAnchor = activeCanvasGenerationDialog
+    ? resolveGenerationAnchor({
+        dialog: activeCanvasGenerationDialog,
+        generatedLayer: activeGenerationLayer,
+      })
+    : null;
+  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,
+    activeGenerationLayer,
+    generationAnchor,
+    generationComposerStyle: resolveGenerationComposerStyle({
+      dialog: activeCanvasGenerationDialog,
+      anchor: generationAnchor,
+      viewport,
+    }),
+    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,
+    },
+  };
+}

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('画布素材已导出');
+  });
+});

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';
+
+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>
+  );
+}

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');
+  });
+});

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],
+  );
+}

src/components/image-editor/useImageCanvasAssetExportWorkflow.ts

@@ -16,7 +16,7 @@ import {
   sanitizeExportFilePart,
 } from './ImageCanvasExportModel';
 
-type AssetExportStatus = {
+export type AssetExportStatus = {
   tone: 'info' | 'success' | 'error';
   message: string;
 };

src/components/image-editor/useImageCanvasStageController.test.tsx

@@ -0,0 +1,152 @@
+/* @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,
+    activeCanvasGenerationDialog: null,
+    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');
+  });
+
+});

src/components/image-editor/useImageCanvasStageController.ts

@@ -0,0 +1,139 @@
+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[];
+  selectedLayerId: string | null;
+  selectedLayerIds: string[];
+  activeCanvasGenerationDialog: CanvasGenerationDialogState | null;
+  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;
+  getCanvasPointFromClient: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number };
+};
+
+export function useImageCanvasStageController({
+  layers,
+  selectedLayerId,
+  selectedLayerIds,
+  activeCanvasGenerationDialog,
+  imageContextMenu,
+  setImageContextMenu,
+  contextMenu,
+  setContextMenu,
+  viewport,
+  canvasSize,
+  selectSingleLayer,
+  hideGeneratedLayerPanelAfterBlur,
+  getCanvasPointFromClient,
+}: UseImageCanvasStageControllerOptions) {
+  const model = useMemo(
+    () =>
+      resolveImageCanvasStageControllerModel({
+        layers,
+        selectedLayerId,
+        selectedLayerIds,
+        activeCanvasGenerationDialog,
+        imageContextMenu,
+        contextMenu,
+        viewport,
+        canvasSize,
+      }),
+    [
+      activeCanvasGenerationDialog,
+      canvasSize,
+      contextMenu,
+      imageContextMenu,
+      layers,
+      selectedLayerId,
+      selectedLayerIds,
+      viewport,
+    ],
+  );
+
+  const clearCanvasFocus = useCallback(() => {
+    selectSingleLayer(null);
+    hideGeneratedLayerPanelAfterBlur();
+    setImageContextMenu(null);
+    setContextMenu(null);
+  }, [
+    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<HTMLButtonElement>, 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,
+  };
+}