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

2026-06-17 14:13:53 +08:00
parent e970d34574 a319d2ae0d
commit f8e063a878
12 changed files with 1440 additions and 304 deletions
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -1,44 +1,17 @@
-import { Check, ChevronLeft, Download, Pencil, X } from 'lucide-react';
-import {
-  type MouseEvent as ReactMouseEvent,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import { 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 {
-  createLayerFromAsset,
-  isGeneratedLayer,
-  isLayerLinkedToAsset,
-  resolveContextMenuPosition,
-} from './ImageCanvasEditorModel';
-import {
-  getGenerationFrameAriaLabel,
-  getGenerationFrameLabel,
-  getLayerKindLabel,
-} from './ImageCanvasGenerationModel';
+import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
+import { resolveContextMenuPosition } from './ImageCanvasEditorModel';
 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(
-    (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],
-  );
+  const removeCanvasLayersLinkedToAssets = useImageCanvasAssetLayerCleanup({
+    layers,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+  });
  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 = (
-    asset: EditorAsset,
-    position?: { x: number; y: number },
-  ) => {
-    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);
-  };
-
-  useImageCanvasAssetPointerDragBridge({
+  const {
+    addAssetLayer,
+    handleCanvasDragOver,
+    handleCanvasDragLeave,
+    handleCanvasDrop,
+  } = useImageCanvasAssetCanvasBridge({
    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">
-          <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 ||
-                !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>
+        <ImageCanvasTopbarView
+          projectId={projectId}
+          projectTitle={projectTitle}
+          projectRenameValue={projectRenameValue}
+          isRenamingProject={isRenamingProject}
+          isProjectRenameSaving={isProjectRenameSaving}
+          projectRenameError={projectRenameError}
+          layers={layers}
+          assetExportStatus={assetExportStatus}
+          isExportingAssets={isExportingAssets}
+          setProjectRenameValue={setProjectRenameValue}
+          startProjectRename={startProjectRename}
+          cancelProjectRename={cancelProjectRename}
+          submitProjectRename={submitProjectRename}
+          resetProjectRenameError={resetProjectRenameError}
+          exportCanvasAssets={exportCanvasAssets}
+        />

        <ImageCanvasStageView
          canvasViewportRef={canvasViewportRef}
--- a/src/components/image-editor/ImageCanvasStageControllerModel.test.ts
+++ b/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,
+      },
+    });
+  });
+});
--- a/src/components/image-editor/ImageCanvasStageControllerModel.ts
+++ b/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,
+    },
+  };
+}
--- a/src/components/image-editor/ImageCanvasTopbarView.test.tsx
+++ b/src/components/image-editor/ImageCanvasTopbarView.test.tsx
@@ -0,0 +1,147 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import { ImageCanvasTopbarView } from './ImageCanvasTopbarView';
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  const id = overrides.id ?? 'layer-a';
+  return {
+    id,
+    resourceId: `resource-${id}`,
+    title: id,
+    src: `data:image/png;base64,${id}`,
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 180,
+    originalWidth: 320,
+    originalHeight: 180,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    ...overrides,
+  };
+}
+
+function renderTopbar(
+  overrides: Partial<
+    Parameters<typeof ImageCanvasTopbarView>[0]
+  > = {},
+) {
+  const props: Parameters<typeof ImageCanvasTopbarView>[0] = {
+    projectId: 'project-a',
+    projectTitle: '默认项目',
+    projectRenameValue: '默认项目',
+    isRenamingProject: false,
+    isProjectRenameSaving: false,
+    projectRenameError: null,
+    layers: [],
+    assetExportStatus: null,
+    isExportingAssets: false,
+    setProjectRenameValue: vi.fn(),
+    startProjectRename: vi.fn(),
+    cancelProjectRename: vi.fn(),
+    submitProjectRename: vi.fn(),
+    resetProjectRenameError: vi.fn(),
+    exportCanvasAssets: vi.fn(),
+    ...overrides,
+  };
+
+  render(<ImageCanvasTopbarView {...props} />);
+
+  return props;
+}
+
+describe('ImageCanvasTopbarView', () => {
+  it('shows the project title and project gallery link', () => {
+    const props = renderTopbar();
+
+    expect(screen.getByRole('heading', { name: '默认项目' })).toBeTruthy();
+    expect(
+      screen.getByRole('link', { name: '返回项目页面' }).getAttribute('href'),
+    ).toBe('/project');
+
+    fireEvent.click(screen.getByRole('button', { name: '编辑项目名称' }));
+
+    expect(props.startProjectRename).toHaveBeenCalledTimes(1);
+  });
+
+  it('submits, resets, and cancels project rename edits', () => {
+    const props = renderTopbar({
+      isRenamingProject: true,
+      projectRenameValue: '草稿项目',
+      projectRenameError: '项目名称不能为空',
+    });
+
+    const input = screen.getByLabelText('项目名称');
+    fireEvent.change(input, { target: { value: '新项目' } });
+    fireEvent.click(screen.getByRole('button', { name: '保存项目名称' }));
+
+    expect(props.setProjectRenameValue).toHaveBeenCalledWith('新项目');
+    expect(props.resetProjectRenameError).toHaveBeenCalledTimes(1);
+    expect(props.submitProjectRename).toHaveBeenCalledWith('project-a');
+    expect(screen.getByRole('alert').textContent).toBe('项目名称不能为空');
+
+    fireEvent.keyDown(input, { key: 'Escape' });
+
+    expect(props.cancelProjectRename).toHaveBeenCalledTimes(1);
+  });
+
+  it('exports only when canvas has exportable layers and shows export status', () => {
+    const exportCanvasAssets = vi.fn();
+    const { rerender } = render(
+      <ImageCanvasTopbarView
+        projectId="project-a"
+        projectTitle="默认项目"
+        projectRenameValue="默认项目"
+        isRenamingProject={false}
+        isProjectRenameSaving={false}
+        projectRenameError={null}
+        layers={[]}
+        assetExportStatus={null}
+        isExportingAssets={false}
+        setProjectRenameValue={vi.fn()}
+        startProjectRename={vi.fn()}
+        cancelProjectRename={vi.fn()}
+        submitProjectRename={vi.fn()}
+        resetProjectRenameError={vi.fn()}
+        exportCanvasAssets={exportCanvasAssets}
+      />,
+    );
+
+    expect(
+      (screen.getByRole('button', { name: '下载画布素材' }) as HTMLButtonElement)
+        .disabled,
+    ).toBe(true);
+
+    rerender(
+      <ImageCanvasTopbarView
+        projectId="project-a"
+        projectTitle="默认项目"
+        projectRenameValue="默认项目"
+        isRenamingProject={false}
+        isProjectRenameSaving={false}
+        projectRenameError={null}
+        layers={[createLayer()]}
+        assetExportStatus={{
+          tone: 'success',
+          message: '画布素材已导出',
+        }}
+        isExportingAssets={false}
+        setProjectRenameValue={vi.fn()}
+        startProjectRename={vi.fn()}
+        cancelProjectRename={vi.fn()}
+        submitProjectRename={vi.fn()}
+        resetProjectRenameError={vi.fn()}
+        exportCanvasAssets={exportCanvasAssets}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '下载画布素材' }));
+
+    expect(exportCanvasAssets).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('status').textContent).toBe('画布素材已导出');
+  });
+});
--- a/src/components/image-editor/ImageCanvasTopbarView.tsx
+++ b/src/components/image-editor/ImageCanvasTopbarView.tsx
@@ -0,0 +1,149 @@
+import { Check, ChevronLeft, Download, Pencil, X } from 'lucide-react';
+
+import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
+import { PlatformTextField } from '../common/PlatformTextField';
+import { EditorIconButton } from './ImageCanvasEditorPrimitives';
+import type { CanvasLayer } from './ImageCanvasEditorTypes';
+import type { AssetExportStatus } from './useImageCanvasAssetExportWorkflow';
+
+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>
+  );
+}
--- a/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.test.tsx
@@ -0,0 +1,252 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  AssetPointerDragState,
+  CanvasLayer,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import {
+  useImageCanvasAssetCanvasBridge,
+  useImageCanvasAssetLayerCleanup,
+} from './useImageCanvasAssetCanvasBridge';
+
+const defaultAsset: EditorAsset = {
+  id: 'asset-1',
+  label: '素材一',
+  src: 'data:image/png;base64,asset-1',
+  width: 320,
+  height: 240,
+  folderId: 'project',
+  sourceKind: 'uploaded',
+  sourceType: 'uploaded',
+  persisted: true,
+  assetObjectId: 'asset-object-1',
+};
+
+const defaultFolder: EditorAssetFolder = {
+  id: 'project',
+  label: '项目素材',
+  collapsed: false,
+  systemDefault: true,
+  persisted: true,
+};
+
+function createLayer(overrides: Partial<CanvasLayer> = {}): CanvasLayer {
+  return {
+    id: 'layer-asset-1',
+    resourceId: 'asset-object-1',
+    title: '素材一',
+    src: 'data:image/png;base64,asset-1',
+    x: 10,
+    y: 20,
+    width: 320,
+    height: 240,
+    originalWidth: 320,
+    originalHeight: 240,
+    zIndex: 1,
+    sourceType: 'uploaded',
+    sourceAssetId: 'asset-1',
+    ...overrides,
+  };
+}
+
+function dispatchPointerEvent(
+  type: string,
+  init: MouseEventInit & { pointerId: number },
+) {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  Object.defineProperty(event, 'pointerId', { value: init.pointerId });
+  window.dispatchEvent(event);
+}
+
+function AssetCanvasBridgeHarness({
+  asset = defaultAsset,
+  resolveCanvasPoint = vi.fn(() => null),
+  appendCanvasLayersWithResources = vi.fn(),
+  captureCanvasHistory = vi.fn(),
+  selectSingleLayer = vi.fn(),
+}: {
+  asset?: EditorAsset;
+  resolveCanvasPoint?: (clientX: number, clientY: number) => {
+    x: number;
+    y: number;
+  } | null;
+  appendCanvasLayersWithResources?: (nextLayers: CanvasLayer[]) => void;
+  captureCanvasHistory?: () => void;
+  selectSingleLayer?: (layerId: string | null) => void;
+}) {
+  const assetPointerDragRef = useRef<AssetPointerDragState | null>({
+    assetId: asset.id,
+    pointerId: 7,
+    startClientX: 10,
+    startClientY: 10,
+    currentClientX: 40,
+    currentClientY: 40,
+    active: true,
+    dropFolderId: null,
+  });
+  const suppressAssetClickRef = useRef(false);
+  const layerCounterRef = useRef(0);
+  const [activeUploadFolderId, setActiveUploadFolderId] = useState('project');
+  const [hoveredLayerId, setHoveredLayerId] = useState<string | null>('hovered');
+  const [assetPointerDrag, setAssetPointerDrag] =
+    useState<AssetPointerDragState | null>(assetPointerDragRef.current);
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+
+  const bridge = useImageCanvasAssetCanvasBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets: [asset],
+    assetFolders: [defaultFolder],
+    layerCounterRef,
+    viewport: { x: 10, y: 20, scale: 2 },
+    canvasSize: { width: 900, height: 640 },
+    resolveAssetFolderId: () => null,
+    resolveCanvasPoint,
+    getCanvasDropPoint: (clientX, clientY) => ({
+      x: clientX - 10,
+      y: clientY - 20,
+    }),
+    setAssetPointerDrag,
+    setActiveUploadFolderId,
+    setUploadDropTarget,
+    setHoveredLayerId,
+    updateAssetMoveDropFolder: vi.fn(),
+    moveAssetToFolder: vi.fn(),
+    captureCanvasHistory,
+    appendCanvasLayersWithResources,
+    selectSingleLayer,
+    addUploadedFiles: vi.fn(),
+  });
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => bridge.addAssetLayer(asset, { x: 450, y: 320 })}
+      >
+        添加到画布
+      </button>
+      <span data-testid="folder">{activeUploadFolderId}</span>
+      <span data-testid="hover">{hoveredLayerId ?? '-'}</span>
+      <span data-testid="drag">{assetPointerDrag ? 'dragging' : 'none'}</span>
+      <span data-testid="drop-target">{uploadDropTarget ?? '-'}</span>
+    </div>
+  );
+}
+
+function AssetCleanupHarness({
+  deletedAssets = [],
+}: {
+  deletedAssets?: EditorAsset[];
+}) {
+  const [layers, setLayers] = useState([
+    createLayer({ id: 'linked', sourceAssetId: 'asset-1' }),
+    createLayer({
+      id: 'kept',
+      resourceId: 'asset-object-2',
+      src: 'data:image/png;base64,asset-2',
+      sourceAssetId: 'asset-2',
+    }),
+  ]);
+  const [selectedLayerId, setSelectedLayerId] = useState<string | null>('linked');
+  const [selectedLayerIds, setSelectedLayerIds] = useState(['linked', 'kept']);
+  const cleanup = useImageCanvasAssetLayerCleanup({
+    layers,
+    setLayers,
+    setSelectedLayerId,
+    setSelectedLayerIds,
+  });
+
+  return (
+    <div>
+      <button type="button" onClick={() => cleanup(deletedAssets)}>
+        清理素材
+      </button>
+      <span data-testid="layers">{layers.map((layer) => layer.id).join(',')}</span>
+      <span data-testid="selected">{selectedLayerId ?? '-'}</span>
+      <span data-testid="selected-many">{selectedLayerIds.join(',')}</span>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetCanvasBridge', () => {
+  it('creates a canvas layer from an asset and clears hover state', () => {
+    const appendCanvasLayersWithResources = vi.fn();
+    const captureCanvasHistory = vi.fn();
+    const selectSingleLayer = vi.fn();
+    render(
+      <AssetCanvasBridgeHarness
+        appendCanvasLayersWithResources={appendCanvasLayersWithResources}
+        captureCanvasHistory={captureCanvasHistory}
+        selectSingleLayer={selectSingleLayer}
+      />,
+    );
+
+    act(() => {
+      screen.getByRole('button', { name: '添加到画布' }).click();
+    });
+
+    expect(captureCanvasHistory).toHaveBeenCalledTimes(1);
+    expect(appendCanvasLayersWithResources).toHaveBeenCalledWith([
+      expect.objectContaining({
+        id: 'layer-asset-1-1',
+        sourceAssetId: 'asset-1',
+        x: 94,
+        y: 64,
+        width: 320,
+        height: 240,
+      }),
+    ]);
+    expect(selectSingleLayer).toHaveBeenCalledWith('layer-asset-1-1');
+    expect(screen.getByTestId('folder').textContent).toBe('project');
+    expect(screen.getByTestId('hover').textContent).toBe('-');
+  });
+
+  it('delegates active pointer drops over the canvas into the layer path', () => {
+    const appendCanvasLayersWithResources = vi.fn();
+    render(
+      <AssetCanvasBridgeHarness
+        resolveCanvasPoint={() => ({ x: 480, y: 640 })}
+        appendCanvasLayersWithResources={appendCanvasLayersWithResources}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 48,
+        clientY: 64,
+      });
+    });
+
+    expect(appendCanvasLayersWithResources).toHaveBeenCalledWith([
+      expect.objectContaining({ sourceAssetId: 'asset-1' }),
+    ]);
+    expect(screen.getByTestId('drag').textContent).toBe('none');
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+  });
+
+  it('removes canvas layers linked to deleted assets and keeps unrelated selection', () => {
+    render(<AssetCleanupHarness deletedAssets={[defaultAsset]} />);
+
+    act(() => {
+      screen.getByRole('button', { name: '清理素材' }).click();
+    });
+
+    expect(screen.getByTestId('layers').textContent).toBe('kept');
+    expect(screen.getByTestId('selected').textContent).toBe('-');
+    expect(screen.getByTestId('selected-many').textContent).toBe('kept');
+  });
+});
--- a/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
+++ b/src/components/image-editor/useImageCanvasAssetCanvasBridge.ts
@@ -0,0 +1,191 @@
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type RefObject,
+  type SetStateAction,
+  useCallback,
+  useMemo,
+} from 'react';
+
+import {
+  createLayerFromAsset,
+  isLayerLinkedToAsset,
+} from './ImageCanvasEditorModel';
+import type {
+  AssetPointerDragState,
+  CanvasLayer,
+  CanvasViewport,
+  EditorAsset,
+  EditorAssetFolder,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
+import { useImageCanvasCanvasDropWorkflow } from './useImageCanvasCanvasDropWorkflow';
+
+type CanvasPoint = { x: number; y: number };
+
+type UploadFilesToCanvasOptions = {
+  folderId?: string;
+  canvasPoint: CanvasPoint;
+  addToCanvas: true;
+};
+
+type UseImageCanvasAssetLayerCleanupOptions = {
+  layers: CanvasLayer[];
+  setLayers: Dispatch<SetStateAction<CanvasLayer[]>>;
+  setSelectedLayerId: Dispatch<SetStateAction<string | null>>;
+  setSelectedLayerIds: Dispatch<SetStateAction<string[]>>;
+};
+
+type UseImageCanvasAssetCanvasBridgeOptions = {
+  assetPointerDragRef: RefObject<AssetPointerDragState | null>;
+  suppressAssetClickRef: RefObject<boolean>;
+  assets: EditorAsset[];
+  assetFolders: EditorAssetFolder[];
+  layerCounterRef: MutableRefObject<number>;
+  viewport: CanvasViewport;
+  canvasSize: { width: number; height: number };
+  resolveAssetFolderId: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint: (clientX: number, clientY: number) => CanvasPoint | null;
+  getCanvasDropPoint: (clientX: number, clientY: number) => CanvasPoint;
+  setAssetPointerDrag: Dispatch<SetStateAction<AssetPointerDragState | null>>;
+  setActiveUploadFolderId: Dispatch<SetStateAction<string>>;
+  setUploadDropTarget: Dispatch<SetStateAction<'canvas' | 'assets' | null>>;
+  setHoveredLayerId: Dispatch<SetStateAction<string | null>>;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  captureCanvasHistory: () => void;
+  appendCanvasLayersWithResources: (nextLayers: CanvasLayer[]) => void;
+  selectSingleLayer: (layerId: string | null) => void;
+  addUploadedFiles: (
+    files: FileList | File[],
+    options: UploadFilesToCanvasOptions,
+  ) => void;
+};
+
+export function useImageCanvasAssetLayerCleanup({
+  layers,
+  setLayers,
+  setSelectedLayerId,
+  setSelectedLayerIds,
+}: UseImageCanvasAssetLayerCleanupOptions) {
+  return useCallback(
+    (deletedAssets: EditorAsset[]) => {
+      if (!deletedAssets.length) {
+        return;
+      }
+      setLayers((currentLayers) =>
+        currentLayers.filter(
+          (layer) =>
+            !deletedAssets.some((asset) => isLayerLinkedToAsset(layer, asset)),
+        ),
+      );
+      setSelectedLayerIds((currentIds) =>
+        currentIds.filter((layerId) =>
+          layers.every(
+            (layer) =>
+              layer.id !== layerId ||
+              !deletedAssets.some((asset) =>
+                isLayerLinkedToAsset(layer, asset),
+              ),
+          ),
+        ),
+      );
+      setSelectedLayerId((currentId) => {
+        if (!currentId) {
+          return currentId;
+        }
+        const currentLayer = layers.find((layer) => layer.id === currentId);
+        return currentLayer &&
+          deletedAssets.some((asset) => isLayerLinkedToAsset(currentLayer, asset))
+          ? null
+          : currentId;
+      });
+    },
+    [layers, setLayers, setSelectedLayerId, setSelectedLayerIds],
+  );
+}
+
+export function useImageCanvasAssetCanvasBridge({
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  assets,
+  assetFolders,
+  layerCounterRef,
+  viewport,
+  canvasSize,
+  resolveAssetFolderId,
+  resolveCanvasPoint,
+  getCanvasDropPoint,
+  setAssetPointerDrag,
+  setActiveUploadFolderId,
+  setUploadDropTarget,
+  setHoveredLayerId,
+  updateAssetMoveDropFolder,
+  moveAssetToFolder,
+  captureCanvasHistory,
+  appendCanvasLayersWithResources,
+  selectSingleLayer,
+  addUploadedFiles,
+}: UseImageCanvasAssetCanvasBridgeOptions) {
+  const addAssetLayer = useCallback(
+    (asset: EditorAsset, position?: CanvasPoint) => {
+      setActiveUploadFolderId(asset.folderId);
+      layerCounterRef.current += 1;
+      const nextLayer = createLayerFromAsset(
+        asset,
+        layerCounterRef.current,
+        viewport,
+        {
+          x: position?.x ?? canvasSize.width / 2,
+          y: position?.y ?? canvasSize.height / 2,
+        },
+      );
+      captureCanvasHistory();
+      appendCanvasLayersWithResources([nextLayer]);
+      selectSingleLayer(nextLayer.id);
+      setHoveredLayerId(null);
+    },
+    [
+      appendCanvasLayersWithResources,
+      canvasSize.height,
+      canvasSize.width,
+      captureCanvasHistory,
+      layerCounterRef,
+      selectSingleLayer,
+      setActiveUploadFolderId,
+      setHoveredLayerId,
+      viewport,
+    ],
+  );
+
+  useImageCanvasAssetPointerDragBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  const canvasDropWorkflow = useImageCanvasCanvasDropWorkflow({
+    assets,
+    assetFolders,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    getCanvasDropPoint,
+    addAssetLayer,
+    addUploadedFiles,
+  });
+
+  return useMemo(
+    () => ({
+      addAssetLayer,
+      ...canvasDropWorkflow,
+    }),
+    [addAssetLayer, canvasDropWorkflow],
+  );
+}
--- a/src/components/image-editor/useImageCanvasAssetExportWorkflow.ts
+++ b/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;
 };
--- a/src/components/image-editor/useImageCanvasStageController.test.tsx
+++ b/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');
+  });
+
+});
--- a/src/components/image-editor/useImageCanvasStageController.ts
+++ b/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,
+  };
+}