# 画布浮动控件设计沉淀：顶部操作区与底部 Dock

> 范围：无限画布的顶部项目操作区、底部画布工具 Dock、小地图，以及工作模式切换。
> 目标：让画布操作控件形成统一的浮动面板系统，并在不同主题和视口下保持稳定对齐。
> 状态：已实现首版，构建与当前画布回归已确认。

## 1. 设计方向

画布本身是创作空间，操作控件不应占用固定内容栏，也不应把按钮散落在画布节点之间。因此控件采用独立浮动面板：

- 左上放置项目菜单、画布名称和重命名入口。
- 右上放置搜索、导入、性能、积分、专注、分享和 Agent 等操作。
- 左下保留画布视图控制和素材空间 Dock。
- 工作模式切换放在右下，与左下 Dock 共用底部安全区，避免顶部中央出现额外的孤立控件。

## 2. 视觉合同

顶部操作区和底部 `FloatingDock`（浮动 Dock）复用 `canvasDockStyle`（画布 Dock 样式合同）：

- `--dock-surface`：浮动面板表面。
- `--dock-border`：主题边界。
- `--elevation-overlay`：面板层级阴影。
- `--dock-command-hover`：控件悬停表面。
- `--dock-command-active`：持续激活状态表面。

普通操作按钮默认透明，只有悬停或持续激活时才显示控件表面；面板本身负责边界和阴影，避免每个按钮都形成独立卡片。

## 3. 工作模式切换

`CanvasWorkspaceModeSwitch`（画布工作模式切换）是右下角独立浮动面板，不再挂在顶部栏中间：

- 触发器与底部 Dock 使用同一高度、圆角、边界和阴影。
- 菜单从触发器上方展开，并与右侧边缘对齐，避免遮挡底部工具栏和画布主体。
- 外层定位使用 `--canvas-inset-x` / `--canvas-inset-y`，与左下视图控制保持同一水平基线。
- 简洁模式和专业模式继续使用原有 `workspaceMode` 状态，不改变节点渲染和生成逻辑。

## 4. 实现地图

- `web/src/pages/canvas/canvas-project-top-bar.tsx`：顶部左右浮动面板，以及工作模式切换组件和下拉菜单。
- `web/src/pages/canvas/project.tsx`：将工作模式切换定位到画布右下角，并与底部控制使用同一安全区。
- `web/src/components/canvas/canvas-zoom-controls.tsx`：底部视图控制 Dock 的既有实现，作为浮动控件视觉基准。
- `web/src/components/canvas/canvas-mini-map.tsx`：小地图节点缩略图、标题标注和视口拖动预览。
- `web/src/components/canvas/canvas-overlay-layer.tsx`：画布浮层的激活层级管理，按点击和焦点提升当前浮层。
- `web/src/lib/canvas/canvas-aceternity-style.ts`：提供 `canvasDockStyle` 样式合同。
- `web/src/styles/globals.css`：维护顶部面板、控件状态和工作模式菜单的唯一样式规则。

## 5. 小地图信息表达

小地图是“定位与导航”视图，不复制完整节点内容，但必须让节点在缩略比例下仍然可识别：

- 图片节点优先复用 `storageKey`、预览地址或导入源生成缩略图；资源通过缓存组件延迟加载。
- 所有节点保留一个短标题标注。标题单行显示并限制最大宽度，过长时省略，悬停可查看完整名称。
- 非图片节点继续使用类型色块；图片缩略图加载失败时回退到类型色块，不伪造媒体内容。
- 可加载缩略图的图片节点不超过 24 个时显示缩略图；超过阈值后统一回退到色块，避免小地图成为媒体解码热点。
- 标注只覆盖在小地图上，不移动画布节点，也不做空间避让；折叠背板内的节点不重复显示。

底部“适应画布”命令的语义是把当前画布内容整体纳入视口，和小地图的导航职责分开：小地图用于定位，适应画布用于一次性恢复内容总览。

## 6. 响应式与交互边界

- 桌面端顶部左右面板保持同一顶部安全区；底部左右面板保持同一底部安全区。
- 窄视口沿用 `--canvas-inset-y + --space-16` 的底部避让规则，避免与移动端底部工具区域重叠。
- 工作模式菜单打开时支持点击外部区域和 `Escape` 关闭。
- `prefers-reduced-motion` 下关闭或缩短面板和选项的进入动画。
- 本次只调整控件位置和视觉层级，不改变菜单命令、模式持久化和画布操作行为。

## 7. 验证与待回归

已完成：

- `git diff --check` 通过。
- Impeccable 受限扫描未发现本次新增的 UI 反模式。
- `web` 目录执行 `bun run build` 通过。
- 当前画布已确认小地图缩略图、标题标注和视口拖动区域正常显示。

待确认：

- 浅色/深色主题下检查顶部左右面板、底部三个 Dock 的边界和阴影一致性。
- 检查工作模式菜单在桌面、窄视口和底部工具栏打开时的对齐与遮挡关系。
- 仍需在更多节点数量、深色主题和极端缩放比例下补充回归；当前构建未覆盖后端集成测试。