拆分图片画布舞台控制层

新增 ImageCanvasStageControllerModel 承载舞台派生状态和右键菜单模型

新增 useImageCanvasStageController 收口清空焦点和右键菜单处理

精简 ImageCanvasEditorView 的舞台控制胶水

更新图片画布拆分计划和 TRACKING 验证记录

TRACKING.md

@@ -140,3 +140,4 @@
 - 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`。

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

@@ -205,16 +205,28 @@
   - 承载素材库与画布之间的桥接工作流：删除素材时清理关联画布图层、素材加入画布创建图层、素材 pointer 拖入画布 / 文件夹、画布区域 drag over / leave / drop 分流，以及拖拽文件上传到画布的参数组装。
   - 主视图继续掌握素材库事实、上传文件读取、工程资源持久化、历史捕获触发时机和实际 API 副作用；该 hook 只负责把已有素材 / 文件 drop 转成画布动作，不反向读取路由、登录态或项目数据。
   - 该 hook 用独立单测覆盖素材建层、pointer drop 入画布和删除素材清理关联图层 / 选中态；原有 pointer drag 和 canvas drop hook 单测继续保留，主视图 DOM 测试继续覆盖真实素材库拖入画布路径。
-  - 本阶段主视图从 1133 行降至 1086 行；下一步可继续抽 `useImageCanvasStageController` 或顶栏视图，但应优先选择能收敛舞台派生状态和右键菜单胶水的深边界。
+  - 本阶段主视图从 1133 行降至 1086 行；下一步可继续抽顶栏视图或更高内聚的舞台控制层，但应优先选择能收敛真实状态规则的深边界。
+
+## 第二十五阶段模块
+
+- `ImageCanvasStageControllerModel.ts`
+  - 承载舞台派生状态和右键菜单模型：选中图层、生成对象锚点、生成输入框位置、选中浮动工具栏位置、图片菜单图层、右键菜单目标图层，以及显示 / 解锁菜单文案判断。
+  - 该模型复用既有图层命令模型与浮层定位模型，不重新实现坐标公式，避免拆分后出现第二套右键目标和浮层定位规则。
+  - 新增单测覆盖生成锚定、选中工具栏位置、右键目标集合、显示 / 解锁判断和菜单位置限制。
+
+- `useImageCanvasStageController.ts`
+  - 承载舞台控制胶水：清空画布焦点、空白画布右键菜单和图层右键菜单处理。
+  - 主视图继续保留工具切换、上传 / 生成入口、图层命令、项目持久化和舞台 pointer 状态机，避免把跨工作流动作塞进单个 hook。
+  - 本阶段主视图从 1086 行降至 993 行；后续若继续拆分，应优先考虑顶栏 / 项目标题区域或把侧栏图层右键入口并入同一舞台菜单控制层。
 
 ## 后续阶段
 
 - 后续可继续选择更高内聚的交互 workflow 或持久化边界，不再把生成链路继续拆成浅层 wrapper。
-- 右键菜单定位、工程资源持久化、舞台派生状态和历史捕获仍在主视图编排，拆分前需要先确认不会破坏多生成对象同时存在、完成时读取最新占位框、素材拖拽上传位置和角色动画优先传 `objectKey` 的历史保护规则。
+- 工程资源持久化、工具切换和历史捕获仍在主视图编排，拆分前需要先确认不会破坏多生成对象同时存在、完成时读取最新占位框、素材拖拽上传位置和角色动画优先传 `objectKey` 的历史保护规则。
 
 ## 验证计划
 
-- `npm run test -- src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx 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/ImageCanvasStageControllerModel.test.ts src/components/image-editor/useImageCanvasStageController.test.tsx 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`
 - `npm run check:encoding`
 - `git diff --check`

src/components/image-editor/ImageCanvasEditorView.tsx

@@ -1,12 +1,5 @@
 import { Check, ChevronLeft, Download, Pencil, X } from 'lucide-react';
-import {
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-  type MouseEvent as ReactMouseEvent,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
 
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformTextField } from '../common/PlatformTextField';
@@ -14,29 +7,14 @@ 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 { resolveContextMenuPosition } from './ImageCanvasEditorModel';
-  isGeneratedLayer,
-  resolveContextMenuPosition,
-} from './ImageCanvasEditorModel';
-import {
-  getGenerationFrameAriaLabel,
-  getGenerationFrameLabel,
-  getLayerKindLabel,
-} from './ImageCanvasGenerationModel';
 import {
   isCanvasGenerationComposerVisible,
   resolveCharacterAnimationPanelStyle,
-  resolveGenerationAnchor,
-  resolveGenerationComposerStyle,
   resolveIconComposerStyle,
   resolveQuickEditPanelStyle,
-  resolveSelectedToolbarStyle,
 } from './ImageCanvasOverlayModel';
 import type {
   AssetPointerDragState,
@@ -59,6 +37,7 @@ import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWork
 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 {
@@ -257,54 +236,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,
@@ -463,6 +394,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,
@@ -540,13 +496,6 @@ export function ImageCanvasEditorView() {
     appendCanvasLayersWithResources,
     selectSingleLayer,
   });
-
-  const clearCanvasFocus = useCallback(() => {
-    selectSingleLayer(null);
-    hideGeneratedLayerPanelAfterBlur();
-    setImageContextMenu(null);
-    setContextMenu(null);
-  }, [hideGeneratedLayerPanelAfterBlur, selectSingleLayer]);
   const {
     canvasMarquee,
     isPanning,
@@ -664,48 +613,6 @@ export function ImageCanvasEditorView() {
 
   deleteLayerByIdRef.current = deleteLayerById;
 
-  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') {

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