1. 总体与环境规格

1.1. 应用程序形态

  • 双重形态: 本质是一个单页 Web 应用 (SPA)，既可以作为独立网站运行，也打包为浏览器扩展。
  • 浏览器扩展行为:
    • 扩展点击逻辑 (background.js): 点击扩展图标时，会检测当前浏览器窗口是否已有打开的 Dango 标签页。如有则跳转并高亮该标签页，否则新建标签页，确保“单例”体验。
    • 兼容性: 同时支持 Chrome (Manifest V3 / chrome API) 和 Firefox (Manifest V2 / browser API)。

1.2. 国际化 (i18n)

  • 语言支持: 支持简体中文 (zh) 和 英文 (en)。
  • 检测与持久化: 优先读取 localStorage (cc-lang)；若无，则检测浏览器语言 navigator.language；默认回退为英文。
  • 动态更新: 切换语言时，实时更新页面标题 (document.title)、DOM 文本 (data-i18n)、悬浮提示 (title) 和 输入框占位符 (placeholder)。

1.3. 主题系统

  • 模式: 提供 🌞 浅色 (Light)、🌙 深色 (Dark) 与 🌓 自动 (Auto) 三种模式。
  • 实现: 基于 CSS 变量 (:root vs [data-theme="dark"])。
  • 自动模式: 跟随系统 prefers-color-scheme，系统主题变化时实时刷新。
  • 持久化: 设置保存在 localStorage (cc-theme)。

2. 画布 (Canvas) 核心规格

2.1. 视图交互

  • 无限画布: 支持无限平移和缩放。
  • 平移 (Pan):
    • 鼠标: 按住空格键 + 拖拽，或按下鼠标中键 + 拖拽。
    • 触控: 单指在空白处拖拽。
  • 缩放 (Zoom):
    • 鼠标: Ctrl/Cmd + 滚轮，或 Ctrl + +/-/= 键。
    • 触控: 双指捏合 (Pinch)，支持中心点缩放计算。
  • 视图重置: 按 Home 键或 Ctrl + 0，视图平滑动画回归中心 (scale: 1.2)。

2.2. 背景与视觉反馈

  • 网格: 默认显示点状网格背景 (radial-gradient)。可设置隐藏。
  • 空状态引导: 当画布无节点时，显示手绘风格的箭头和提示文字（“输入想法，开启你的画布”），引导用户关注输入框。
  • 拖拽反馈: 当用户拖拽文件进入画布区域时，画布边缘显示虚线框高亮 (.drag-over)，提示可释放导入。

3. UI 组件规格

3.1. 主控制面板 (#ui-layer)

  • 形态: 位于左上角的悬浮面板。默认收起为方形图标，鼠标悬浮 (hover) 或 内部聚焦 (focus-within) 时展开。
  • 移动端适配: 移动端点击面板区域时强制展开 (.mobile-active)，点击画布区域时自动收起。
  • 输入区 (textarea):
    • 支持批量输入。
    • 解析规则: 仅按换行符创建多个节点。
    • 布局规则: 新节点组放置在现有节点包围盒最右侧 x + 200px 的空白区域起点。
    • 快捷键: Ctrl/Cmd + Enter 立即生成节点，Enter 仅换行。
  • 操作堆栈 (.action-stack):
    • 采用 3D 翻转动画结构。
    • 正面: [导出] [导入] [清空]。
    • 反面 (点击导出后): [LINK] [DANGO] [EMBED]。
    • 自动复位: 导出面板翻转后，若无操作或点击外部，会自动翻转回正面。

3.2. 顶部状态栏

  • Logo: 根据日期自动显示节日 Emoji（如 🧧春节, 🎃万圣节, 🎄圣诞节等），平时显示 ✨。
  • 功能区: 语言切换、主题切换、设置、帮助。

3.3. 模态框与弹窗

  • 设置面板 (#settings-modal):
    • 隐藏网格点。
    • Alt 键兼任 Ctrl 功能 (方便单手操作)。
    • 手写风格 (实验性)。
  • 帮助面板 (#help-modal): 列出快捷键，提供 GitHub/反馈/关于 入口。
  • 关于弹窗 (#about-card): 包含版本信息、简介、GitHub Star 引导、博客链接。支持点击遮罩层关闭。
  • Toast 通知: 底部浮出提示。对于“清空”、“导入”等破坏性操作，提供 [撤销] 和 [导出备份] 按钮作为安全网。

4. 画布元素规格

4.1. 节点 (Node)

  • 渲染逻辑:
    • 普通文本: 支持 Markdown 基础语法（粗体 **、斜体 *）。
    • Todo 列表: 识别 [ ] 或 [x]。渲染为带复选框的列表。
      • 交互: 点击复选框区域 (.todo-checkbox-wrapper) 可直接切换完成状态（修改原始文本），并触发重绘。
      • 样式: 包含 Todo 的节点强制左对齐。
    • 链接节点: 识别 URL。渲染为带下划线的文本，选中节点后右侧悬浮“跳转按钮”。
    • 图片节点: 内容完全匹配 Markdown 图片格式 ![alt](url) 时渲染为图片。
      • 初始尺寸: 默认小尺寸 (宽 100px，按原始比例计算高度)。
      • 尺寸切换: 选中图片节点时显示尺寸按钮，点击按 S(100) → L(200) 循环。
      • 数据同步: 尺寸变化仅更新节点已有 w/h 字段。
  • 编辑:
    • 双击节点或按 Enter 进入编辑模式 (contentEditable)。
    • 编辑时暂时移除 Markdown 渲染，显示原始文本。
    • Shift + Enter 换行，Enter 完成编辑，Esc 取消。
  • 手写风格: 开启设置后，应用 Architects Daughter (英) / LXGW WenKai (中) 字体，并应用不规则边框圆角。

4.2. 连接线 (Link)

  • 渲染: SVG <line> 元素。
  • 交点计算: 使用 getEdgeIntersection 算法，确保连线精确指向节点矩形的边缘，而非中心点。
  • 样式: 虚化处理 (opacity: 0.35)，箭头为 V 形描边 (path stroke) 而非填充三角形，更具手绘感。

5. 核心交互与操作

5.1. 历史记录 (Undo/Redo)

  • 机制: 基于快照 (Snapshot) 的历史栈。
  • 容量: 最大 50 步。
  • 触发: 节点增删改、移动、连线、属性变更、选中状态变化均记录历史。
  • 快捷键: Ctrl+Z (撤销), Ctrl+Y 或 Ctrl+Shift+Z (重做)。

5.2. 鼠标/触控操作

  • 选择: 单击选中；拖拽框选；Ctrl + 单击 (多选/反选)。
  • 移动: 拖拽选中节点。
  • 克隆: 按住 Ctrl (或 Alt 若开启设置) 拖拽节点，会在原位置保留副本，拖走新生成的节点（原地克隆逻辑）。
  • 双击:
    • 节点上双击进入编辑。
    • 空白区域双击在指针位置创建新节点并自动进入编辑。
  • 触控特化:
    • 轻触: 选中节点/组。
    • 拖拽: 移动节点/平移画布。
    • 双指捏合: 缩放画布。
    • 拟态双击: 短时间内两次轻触同一节点触发编辑。

5.3. 快捷键体系

  • 基础: Del (删除), Space (平移), Home (归位)。
  • 组合: Ctrl+G (编组), Ctrl+Shift+G (解组)。
  • 连线 (Ctrl+L): 状态机循环：
    1. 无 -> 建立连线 (无方向)。
    2. 无方向 -> 指向目标 (Target)。
    3. 指向目标 -> 指向源头 (Source) (若反向选中则逻辑相应调整)。
    4. 指向源头 -> 删除连线。
  • 对齐:
    • Alt + W/A/S/D (顶/左/底/右对齐)。
    • Alt + H/J (水平/垂直居中)。
    • Alt + Shift + H/J (水平/垂直分布)。
    • 智能对齐 (Alt + .): 自动识别选中节点的行结构，执行平滑动画 (animateNodesTo) 排列整齐，并保持整体重心位置不变。
  • 聚光灯 (Q): 按住 Q 键压暗背景，高亮鼠标位置。

6. 数据与输入输出

6.1. 数据存储

  • 本地: localStorage (cc-canvas-data) 实时自动保存。
  • 数据结构: 包含 nodes, groups, links 数组。

6.2. 导出

  • JSON (.dango): 完整数据备份。
  • 链接 (Link):
    • 使用 LZString 压缩当前数据为 URL Hash。
    • 复制分享链接到剪贴板。
  • 嵌入代码 (Embed):
    • 生成 <iframe> 嵌入代码块并复制到剪贴板。

6.3. 导入

  • 支持点击按钮选择文件，或直接拖拽 .dango/.json 文件到画布。
  • URL 加载: 打开页面时若 URL Hash 存在数据，优先解压加载 Hash 数据（分享预览模式）。

7. 特殊模式

7.1. 嵌入模式 (Embed Mode)

  • 触发: URL 参数 ?embed=true。
  • UI 变化: 隐藏左上角主控面板。右下角显示“预览信息”和“打开完整版”按钮。
  • 行为: 允许用户交互（拖拽、编辑），但不会将修改保存到 localStorage，刷新即恢复原状。适用于博客/文档嵌入演示。