dsh-minimap
为 dsh web GUI 的侧边文件查看器加一条 VS Code 风格的缩略图滚动条（minimap）：宽体文字缩略 + 可拖动的视口框，在长文件中快速定位。
A VS Code-style minimap for the dsh web GUI's side file viewer: a wide text thumbnail with a draggable viewport box for fast navigation in long files.
中文 · English
中文
功能
- 在 Files 侧栏文本编辑器的右缘叠加整篇文档的微型文字缩略图
- 半透明视口框实时跟随滚动：点击跳转、按住拖动、悬停滚轮均可定位
- 语法着色：滚动经过的行会带上与编辑器一致的高亮色，自动适配明暗主题
- 宽度随侧栏自适应（约为编辑器宽度的 22%，钳制在 56–110px）；编辑器内容区自动预留「缩略图宽度 + 5px」的间隙，长行文字不会被遮挡
- 拖到底即真正到底：比例映射以编辑器的真实滚动范围为基准
- 纯叠加层：不改动侧栏任何组件，侧栏未启用时静默不渲染；多标签页各自独立，关闭标签页或卸载插件后完全清理
安装
从 npm 安装（推荐）：
dsh plugin --profile web add dsh-minimap
或从 GitHub 源码安装：
dsh plugin --profile web add github:ping1999/dsh-minimap
安装后重启 web 服务生效：
pnpm dsh web
兼容性：已验证 dsh 0.1.5-rc.2 + dsh-better-sidebar 0.19.1（含 0.19 起文件编辑器迁入 DSH 原生右侧栏的 DOM 变化）；向下兼容 dsh 0.1.5-rc.1 / dsh-better-sidebar 0.19.0。
使用
打开任意会话，在右侧 Files 侧栏打开一个文本文件，编辑器右缘即出现缩略图：
- 滚动编辑器 → 缩略图视口框同步移动
- 点击缩略图任意位置 → 编辑器跳转到对应位置（视口居中）
- 按住视口框拖动 → 编辑器跟随滚动（鼠标与触屏均可）
- 悬停缩略图滚轮 → 等效于滚动编辑器（含触控板横向滚动）
限制
- 仅对 CodeMirror 6 文本查看器生效（当前即 dsh-better-sidebar 的文件查看器）；图片 / PDF / Markdown 预览不会出现缩略图
- 语法着色是渐进式的：CM6 只渲染可视行，行滚入视野至少一次后才有颜色
- 安装 / 升级后需重启 web 服务（与所有 profile bundle 一致）
- 暂无设置项
English
Features
- Overlays a miniature text thumbnail of the whole document on the right edge of the Files sidebar's text editor
- A translucent viewport box tracks scrolling live — click to jump, drag to scroll, or hover and use the wheel
- Syntax colors: lines pick up the editor's real highlight colors once scrolled into view, adapting to dark/light themes
- Width adapts to the sidebar (~22% of the editor width, clamped to 56–110 px); the editor reserves the thumbnail's width plus a fixed 5 px gap, so long lines are never covered
- Dragging the box to the bottom reaches the true end of the document — the mapping is anchored to the editor's real scroll range
- Pure overlay: the sidebar is never modified or even aware of the plugin; each tab gets its own instance, and closing a tab or uninstalling removes everything
Install
From npm (recommended):
dsh plugin --profile web add dsh-minimap
Or from GitHub source:
dsh plugin --profile web add github:ping1999/dsh-minimap
Restart the web server to take effect:
pnpm dsh web
Compatibility: verified with dsh 0.1.5-rc.2 + dsh-better-sidebar 0.19.1 (including the 0.19 change that moved the file editor into DSH's native right sidebar); remains compatible down to dsh 0.1.5-rc.1 / dsh-better-sidebar 0.19.0.
Usage
Open any session, open a text file in the Files sidebar, and the minimap appears at the editor's right edge:
- Scroll the editor → the viewport box follows
- Click anywhere on the minimap → jump there (the viewport centers)
- Drag the viewport box → the editor scrolls along (mouse or touch)
- Hover the minimap and use the wheel → same as scrolling the editor (trackpad horizontal scroll included)
Limitations
- Only works with the CodeMirror 6 text viewer (currently dsh-better-sidebar's file viewer); image / PDF / Markdown previews get no minimap
- Syntax coloring is progressive: CM6 renders only visible lines, so a line gets its colors after being scrolled into view at least once
- A web-server restart is required after install/upgrade (same as every profile bundle)
- No settings yet
内部实现 · Internals
架构与实现细节（滚动映射、着色策略、几何参数、测试与开发流程）见 AGENTS.md。
Architecture and implementation details (scroll mapping, coloring strategy, geometry, testing and dev workflow) live in AGENTS.md.
License
MIT
