Proposal: fullscreen zoom viewer for Mermaid diagrams(文档站 Mermaid 图全屏缩放查看器)— implemented, branch ready

[JuwanXu]

TL;DR

文档网站的 Mermaid 图(如 agent-lifecycle 时序图,9 个 participant 多层 alt/loop)目前无法在浏览器里放大查看。本提案给全站图表加一个"点击全屏 + 缩放平移"查看器,已完整实现并通过全部本地门禁,分支就绪,欢迎合入:

• 分支:https://github.com/JuwanXu/deepseek-harness/tree/feat/docs-site-mermaid-zoom-viewer(8 commits,基于 master b150a551)
• 在线浏览 diff:master...JuwanXu:feat/docs-site-mermaid-zoom-viewer

交互设计

• 图表光标变 zoom-in,悬停显示"点击放大";点击打开全屏遮罩层,SVG 按"适配视口"比例居中展示——全程矢量渲染,任意倍率不失真
• 滚轮以指针位置为中心缩放、拖拽平移、双指捏合(触屏)、+/− 按钮、双击复位
• Esc / 关闭按钮 / 点击图外任意区域均可关闭;打开期间锁定页面滚动;缩放钳制在自然尺寸的 0.05×–10×
• 渐进增强:图表容器变为可聚焦按钮(tabindex + role="button" + 本地化提示),Tab 聚焦后 Enter/Space 打开,关闭后焦点还原到该图表
• 配色走 VitePress 主题变量,深浅色模式自适应;禁用 JavaScript 时页面行为与现状完全一致

实现要点

• 新增最小 theme 目录 website/.vitepress/theme/:index.ts 扩展默认主题并加载副作用模块 mermaid-viewer.ts(约 250 行:document 级事件委托匹配 .mermaid 容器,插件重渲染无需逐实例绑定;遮罩层持有打开时刻的 SVG 克隆,不影响页面渲染)
• @panzoom/panzoom 精确固定 4.6.2,仅作为 website 的 devDependency;因该包没有 exports 映射导致 SSR 解析失败,在 config 中为其配置了 vite.ssr.noExternal
• 两个值得评审关注的实现细节:遮罩层必须先挂载再初始化 Panzoom(其构造函数对 detached 元素直接抛错);关闭判定带 5 px 指针位移阈值,平移后松手不会误触发关闭
• 设计决策记录(含中文版、备选方案分析与风险):.agents/notes/implemented/process/2026-08-23-docs-site-mermaid-zoom-viewer.md

验证

• pnpm run doc-sync:28/28 门禁通过(含 website:build、docs:check、Agent Note 格式、中英配对一致性)
• oxlint 对改动文件零告警;预推增量 typecheck 通过
• 对构建产物 preview 的浏览器坐标级断言(Playwright):打开适配、滚轮/双击/按钮行为、适配态与放大态下各关闭路径、拖拽松手不误关、键盘完整路径(Tab→Enter→Esc→焦点还原)、暗色主题渲染、禁 JS 基线不变——全部通过

请求

该镜像仓库未开放 Pull Request 功能。若欢迎此贡献,请告知期望的合入路径:开放 PR、给予内部开发仓库(deepseek-harness/deepseek-harness)的提交权限,或由维护者直接从上述分支 cherry-pick 均可。