dsh-mermaid-smooth 0.1.0 → 0.2.1

package/README.md

@@ -7,11 +7,30 @@ default, with smooth zoom and pan, a per-fence diagram/code toggle at each
 card's top-right, a persisted per-fence preference, dark-mode follow, and a
 fully bundled offline engine (zero CDN).
 
+## Supported diagram types
+
+The plugin bundles **Mermaid 11.17.2** locally, so it renders these diagram
+types without adding another charting library:
+
+| Type | Syntax |
+| --- | --- |
+| Flowchart | `flowchart` / `graph` |
+| Sequence diagram | `sequenceDiagram` |
+| State diagram | `stateDiagram` |
+| Class diagram | `classDiagram` |
+| Mind map | `mindmap` |
+| Gantt chart / timeline | `gantt` / `timeline` |
+| ER diagram | `erDiagram` |
+| User journey, pie, Git, Sankey, XY, Kanban, and architecture diagrams | Supported by the bundled Mermaid engine |
+
 - **Default diagram** — fences in assistant messages render as SVG diagrams
   the moment they are complete; non-mermaid code blocks are untouched.
 - **Smooth interaction** — cursor-anchored wheel zoom over one composed
   transform (with a short ease-out), direct pointer drag, double-click to
   fit. Reduced-motion preferences disable all easing.
+- **Useful diagram tools** — fit to width or the whole diagram, copy the
+  Mermaid source, and download the rendered SVG. Press <kbd>Esc</kbd> to exit
+  fullscreen.
 - **Toggle at top-right** — every diagram card has a 图/文案 (diagram/code)
   switch; several fences in one message toggle independently.
 - **Per-fence memory** — the toggle state persists in localStorage keyed by
@@ -22,6 +41,23 @@ fully bundled offline engine (zero CDN).
   (zero CDN), and a failed fence keeps its original code with an inline
   error banner. Uninstalling restores the conversation verbatim.
 
+## Diagram card toolbar
+
+Every card carries an icon toolbar at its top-right; hover an icon for its
+tooltip.
+
+| Icon | Action | What it does |
+| --- | --- | --- |
+| ↔ | Fit width | Scale the diagram to the card width (the initial state) |
+| ⊙ | Fit diagram | Scale so the entire diagram fits inside the viewport |
+| ⧉ | Copy source | Copy this fence's Mermaid source to the clipboard. The async Clipboard API is used when available, with a hidden-textarea fallback; a brief "Source copied" status confirms success and "Could not copy source" reports failure. |
+| ↓ | Download SVG | Save the rendered diagram as `mermaid-diagram.svg` — a vector file that stays sharp at any zoom level in browsers, docs, and design tools. If the diagram has not finished rendering, a "Diagram is not ready" status appears instead. |
+| `</>` | Diagram / code | Switch between the diagram and its source; the choice is remembered per fence |
+| ⛶ | Fullscreen | Show the diagram full-screen (diagram view only). <kbd>Esc</kbd> exits and focus returns to the fullscreen button. |
+
+Toolbar status messages auto-clear after about two seconds and are announced
+to screen readers via `aria-live="polite"`.
+
 ## Screenshots
 
 ![1](docs/1.png)
@@ -32,10 +68,25 @@ fully bundled offline engine (zero CDN).
 
 ## Install
 
-Two ways — pick one, then restart DSH Web (the current session ends, but DSH
+dsh-mermaid-smooth is a plugin for the DeepSeek Harness (dsh) web UI. Before
+proceeding, make sure the dsh CLI and web environment are installed and set
+up.
+
+Four ways — pick one, then restart DSH Web (the current session ends, but DSH
 sessions are persisted on disk and can be resumed after restart).
 
-**1. From GitHub (pinned to a verified commit)**
+**1. npm package (recommended, simplest)**
+
+```sh
+dsh plugin --profile web add dsh-mermaid-smooth
+```
+
+Verified working: the tarball ships the prebuilt `lib/client.js`, so nothing
+is compiled at install time. pnpm may auto-add the package to
+`minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml` (because the
+package was just published) — that is expected and harmless.
+
+**2. From GitHub (pinned to a commit)**
 
 ```sh
 dsh plugin --profile web add 'github:gitByteFree/dsh-mermaid-smooth#<full-commit-sha>'
@@ -46,7 +97,24 @@ history page); later changes on `main` will not silently alter installed code.
 The source is installed and built at install time (`prepare` runs the esbuild
 bundle), so git and Node.js ≥ 20 are required.
 
-**2. Local clone (for development)**
+**3. From a release tarball (offline / where git is inconvenient)**
+
+Download `dsh-mermaid-smooth-0.2.0.tgz` from this repo's
+[Releases](https://github.com/gitByteFree/dsh-mermaid-smooth/releases) (it
+contains the prebuilt `lib/client.js`, so no `prepare` script runs at install
+time), then run from the directory you downloaded it to:
+
+```sh
+dsh plugin --profile web add ./dsh-mermaid-smooth-0.2.0.tgz
+```
+
+`0.2.0` above is a real filename, not a placeholder — match the version you
+downloaded and drop any `<...>` brackets (zsh reads a bare `<...>` as input
+redirection and fails with "no such file or directory"). Keep the `./`
+prefix: `dsh plugin add` anchors `./`-relative paths to your current
+directory, while a bare filename would be looked up inside the profile.
+
+**4. Local clone (for development)**
 
 ```sh
 git clone git@github.com:gitByteFree/dsh-mermaid-smooth.git

package/README.zh.md

@@ -4,13 +4,44 @@
 
 将 DeepSeek Harness（dsh）Web 对话中的 mermaid 代码围栏**默认渲染为图**：丝滑的缩放与拖拽，每张图右上角提供图/文案切换，偏好按围栏记忆，明暗主题跟随，渲染引擎完全本地打包（零 CDN）。
 
+## 支持的图表类型
+
+插件本地打包了 **Mermaid 11.17.2**，无需再接入其他图表库，即可渲染以下图表：
+
+| 类型 | 语法 |
+| --- | --- |
+| 流程图 | `flowchart` / `graph` |
+| 时序图 | `sequenceDiagram` |
+| 状态图 | `stateDiagram` |
+| 类图 | `classDiagram` |
+| 思维导图 | `mindmap` |
+| 甘特图 / 时间线 | `gantt` / `timeline` |
+| ER 图 | `erDiagram` |
+| 用户旅程、饼图、Git 图、桑基图、XY 图、看板、架构图等 | 由内置 Mermaid 引擎支持 |
+
 - **默认成图** — 助手消息中的 mermaid 围栏一旦完整立即渲染为 SVG 图；非 mermaid 代码块不受影响。
 - **丝滑交互** — 滚轮缩放以指针为锚点（单一 transform 合成 + 短过渡），拖拽平移 1:1 跟手，双击适应/复位；系统开启「减少动态效果」时全部动画禁用。
+- **实用工具** — 可一键适应宽度或全图、复制 Mermaid 源码、下载渲染后的 SVG；全屏时按 <kbd>Esc</kbd> 即可退出。
 - **右上角切换** — 每张图卡片有「图/文案」切换按钮；一条消息中的多个围栏各自独立。
 - **按围栏记忆** — 切换状态存于 localStorage（以围栏源码为键），刷新页面、重连后保持。
 - **主题跟随** — 图随 GUI 明暗主题重新渲染。
 - **安全离线** — mermaid 以 securityLevel 'strict' 运行（内置消毒、不绑点击事件），引擎打包进插件本体（零 CDN）；渲染失败的围栏保留原代码并内联错误条。卸载插件后对话原样还原。
 
+## 图表卡片工具栏
+
+每张图卡片右上角有一排图标按钮，悬停可见文字提示：
+
+| 图标 | 功能 | 说明 |
+| --- | --- | --- |
+| ↔ | 适应宽度 | 将图缩放到卡片宽度（也是初始状态） |
+| ⊙ | 适应全图 | 缩放到整张图完整显示在视口内 |
+| ⧉ | 复制源码 | 把当前围栏的 Mermaid 源码复制到剪贴板。优先使用异步 Clipboard API，不可用时降级为隐藏 textarea 方案；成功显示「已复制源码」，失败显示「无法复制源码」。 |
+| ↓ | 下载 SVG | 把渲染好的图保存为 `mermaid-diagram.svg` —— 矢量文件，在浏览器、文档、设计工具里任意缩放都不失真。图尚未渲染完成时会显示「图表尚未渲染完成」。 |
+| `</>` | 图 / 文案 | 在图与源码之间切换；按围栏记忆偏好 |
+| ⛶ | 全屏 | 全屏查看图（仅图视图）。<kbd>Esc</kbd> 退出，焦点回到全屏按钮。 |
+
+工具栏的状态提示约两秒后自动消失，并通过 `aria-live="polite"` 播报给屏幕阅读器。
+
 ## 截图
 
 ![1](docs/1.png)
@@ -21,9 +52,19 @@
 
 ## 安装
 
-两种方式任选其一，装完重启 DSH Web 即生效（当前会话会中断，但 DSH 会话有磁盘持久化，重启后可以恢复）。
+dsh-mermaid-smooth 是 DeepSeek Harness (dsh) Web 界面的插件。使用前请确保你已安装并配置好 dsh 命令行工具及 Web 环境。
+
+四种方式任选其一，装完重启 DSH Web 即生效（当前会话会中断，但 DSH 会话有磁盘持久化，重启后可以恢复）。
 
-**方式一：从 GitHub 安装（固定到指定提交）**
+**方式一：npm 正式包（推荐，最简单）**
+
+```sh
+dsh plugin --profile web add dsh-mermaid-smooth
+```
+
+安装时无需编译。pnpm 可能会自动把该包加进 profile 的 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`（因为包刚发布）——这是预期行为，无副作用。
+
+**方式二：从 GitHub 安装（固定到指定提交）**
 
 ```sh
 dsh plugin --profile web add 'github:gitByteFree/dsh-mermaid-smooth#<40位commit>'
@@ -31,7 +72,17 @@ dsh plugin --profile web add 'github:gitByteFree/dsh-mermaid-smooth#<40位commit
 
 固定到你想装的 commit（如仓库提交历史页显示的 main HEAD），之后 main 的新改动不会静默改变已安装代码。源码安装时会在本机构建（`prepare` 脚本执行 esbuild 打包），需要 git 与 Node.js ≥ 20。
 
-**方式二：克隆后从本地路径安装（开发迭代）**
+**方式三：从 Release tarball 安装（离线 / 不便走 git 的环境）**
+
+从本仓库 [Releases](https://github.com/gitByteFree/dsh-mermaid-smooth/releases) 下载 `dsh-mermaid-smooth-0.2.0.tgz`（内含构建好的 `lib/client.js`，安装时无需执行任何 prepare 脚本），进入下载目录后执行：
+
+```sh
+dsh plugin --profile web add ./dsh-mermaid-smooth-0.2.0.tgz
+```
+
+命令里的 `0.2.0` 是**真实文件名**，不是占位符 —— 请改成你实际下载的版本，并去掉一切 `<...>` 尖括号（zsh 会把裸的 `<...>` 当作输入重定向，报「没有那个文件或目录」）。保留 `./` 前缀：`dsh plugin add` 只把 `./`、`../` 开头的路径锚定到你当前所在目录，裸文件名会在 profile 目录里查找。
+
+**方式四：克隆后从本地路径安装（开发迭代）**
 
 ```sh
 git clone git@github.com:gitByteFree/dsh-mermaid-smooth.git