@dsh-plug/dsh-sidebar-epub

DSH web 插件：为 dsh-better-sidebar 的侧边栏编辑器提供 EPUB 电子书预览。通过 ctx.betterSidebar.registerFileViewer 注册 .epub 文件预览器，渲染库 epub.js（连同 jszip）只进本插件的 bundle，不拖大 better-sidebar 主包。

DSH web plugin: an EPUB ebook previewer for the better-sidebar editor. Registers the .epub file viewer through ctx.betterSidebar.registerFileViewer; the epub.js render library (with jszip) lives in this plugin's bundle only, keeping better-sidebar's own client bundle small.

功能 / Features

点击 .epub 文件即在侧边栏阅读器中打开（分页双栏 / 连续滚动两种版式）
目录抽屉（TOC，当前章节高亮）、上一页/下一页与键盘 ←/→ 翻页、章节内页码或全书进度百分比
阅读进度（CFI）按文件路径持久化，重开/跨会话自动续读
设置行（DSH 设置页「侧边卡片」→ EPUB 卡片齿轮）：主题（明亮/护眼/暗黑）、字号、版式、双栏对开、页边距
错误降级：损坏或非 EPUB 文件显示原因 + 下载按钮（与 office 插件同款兜底）
zh / en 界面文案，随 DSH locale 切换；安装 @huanlin/dsh-plugin-better-locale 后可加 ja 等覆盖语言（src/client/dictionaries.ts）

安装 / Install

市场受管安装（在 DSH 所在环境的终端执行）：

dsh plugin --profile web add @dsh-plug/dsh-sidebar-epub

本地开发挂载（link 方式）：

本仓库 pnpm install && pnpm build（typecheck 前需已构建 dsh-better-sidebar 的 lib/types）。
~/.dsh/profiles/web/package.json 的 dependencies 加 "@dsh-plug/dsh-sidebar-epub": "link:<本仓库绝对路径>"，并在 dsh.profile.bundles 数组追加包名。
cd ~/.dsh/profiles/web && pnpm install。
浏览器硬刷新（Cmd/Ctrl+Shift+R）。client-only 改动无需重启 DSH。

开发 / Development

pnpm install
pnpm build        # tsdown 双产物（lib/index.js + lib/client.js）+ tsc 声明
pnpm typecheck    # tsc --noEmit（需 better-sidebar 的 lib/types 已构建）
pnpm test         # vitest（registration / toc / progress / settings）
pnpm watch        # tsdown --watch

client bundle 是单文件 CJS closure（codeSplitting: false），经 window.__ModuleLoader__.load 注册；react / dsh-client-runtime 等 externals 走 DSH 模块表，其余（epub.js + jszip 等）全部内联。jszip 别名到其浏览器预构建产物（Rolldown CJS 降级后不遵守其 browser remap，见 tsdown.config.ts）。

已知限制 / Known limitations

设置热生效：设置行写入后需重新打开书才生效（flow 变更需要重建 rendition）；字号/主题的实时调节在路线图内。
分页版式忽略页边距（epub.js 的分栏布局不支持 body padding；页边距仅作用于连续滚动版式）。
竖排 / RTL：epub.js 对 writing-mode: vertical-rl 支持有限，命中时排版可能降级为横排。
换肤不实时：iframe 内容调色板是字面值（iframe 文档读不到宿主 CSS 变量），换肤后重开书才跟随；阅读器外壳（工具条/目录/翻页条）令牌驱动，实时跟随。
内容安全模型：EPUB 内容在 epub.js 的同源 iframe 内渲染，与常见桌面阅读器同级信任模型——只打开你信任的电子书。

路线图 / Roadmap

书内搜索（spine 逐节加载 + 命中列表跳转）
与 @hongling/dsh-search-plugin 协同：host 半 EPUB 全文抽取 → openFile reveal 跳节高亮（本插件已预留 reveal 结构镜像与 <mark> 高亮管线）
书签/批注、封面书架 tab

仓库约束 / Repository rules

禁止修改 DSH 官方源码（~/.dsh/source/current 零写入）；只消费 better-sidebar 的公开服务与 /sidebar/file、/sidebar/api/settings.get 路由。
代码改动走 feat/* / fix/* 分支 + PR；仅纯文档改动可直接推 main。
发布清单的依赖字段不得出现 cordis；scripts 不得含 install hooks。
挂载只走 cordis.patch.yml + profile 机制。

License

AGPL-3.0（见 LICENSE）

dsh-sidebar-epub

Install

Source

Readme