dsh-latex-formula-editor 1.0.0 → 1.1.1

package/README.en.md

@@ -1,38 +1,150 @@
-# dsh-latex-formula-editor
-
-> A LaTeX formula editor for the DSH sidebar: offline rendering, tile-based symbol input, formula templates, favourites, image/document OCR, multi-format export and sharing.
-
-![Plugin UI](docs/img/editor.png)
-
-## Install
-
-```bash
-git clone https://github.com/jiahui-huang1/dsh-latex-formula-editor.git
-pnpm dsh plugin add ./dsh-latex-formula-editor
-```
-
-Enable **LaTeX Formula Editor** in the DSH sidebar (entry id `latex-editor`).
-
-## Features
-
-- **Quick tools** — ten tiles (common symbols, Greek, fractions/calculus, roots, limits & logs, trigonometry, integrals, large operators, brackets, matrices); hover to expand the grouped symbol panel, click to insert.
-- **Templates** — algebra, geometry, inequalities, integrals, matrices, trigonometry, statistics, sequences, physics, chemistry.
-- **Format row** — colour picker, rendered font menu, rendered size menu, environment wrapper (align/aligned/gathered/cases/split/array/eqnarray/none), clear, undo, import, favourite.
-- **Export** — images (SVG/PNG/JPG), code (LaTeX/AsciiMath/Typst/SVG Code/HTML inline & display/MathML variants/OMML), escaping (backslash, `$…$`, `$$…$$`, `\(…\)`, `\[…\]`, JSON) and share links.
-- **Favourites** — title, timestamp, render and source per entry; rename, copy, delete, insert; searchable; configurable cap (10 by default).
-- **Recognition** — image OCR (drag & paste) and document OCR (page by page, download as Word/LaTeX/Markdown, results kept for 15 days).
-- **UI** — 150% default scale, light/dark theme, 简体中文 / 繁體中文 / English.
-
-![Document OCR](docs/img/doc-ocr.png)
-
-## Settings
-
-Settings → OCR service: use the Harness model or an OpenAI-compatible endpoint. Rendering and export are fully offline; only OCR sends an image.
-
-## Requirements
-
-DSH ≥ 1.0 (`dsh.bundle.patch` + `dsh.client`). No build step; MathJax 3 and PDF.js ship with the plugin.
-
-## Licence
-
-MIT
+# DSH LaTeX Formula Editor
+
+English · [简体中文](README.md)
+
+[![npm](https://img.shields.io/npm/v/dsh-latex-formula-editor.svg)](https://www.npmjs.com/package/dsh-latex-formula-editor)
+[![topic](https://img.shields.io/badge/topic-dsh--plugin-0e7490.svg)](https://github.com/topics/dsh-plugin)
+
+A free, open-source and fully offline LaTeX formula editor that lives in the **left sidebar** of the DeepSeek Harness Web UI (icon `Σ`).
+Interaction follows [latexlive.com](https://www.latexlive.com/), but everything runs on your own machine: maths is rendered by the
+bundled MathJax, PDFs are parsed by the bundled PDF.js — no account, no quota, no uploads (except the recognition backend you configure).
+
+- Sidebar entry → one panel with five views: **Editor / Image OCR / Document OCR / Favourites / Help**
+- Live LaTeX rendering (MathJax 3.2.2, SVG output, offline)
+- UI scale **125%** by default (Settings → UI scale, 100%–200%)
+- Light / dark theme switch (follows the system by default), 简体中文 / 繁體中文 / English
+- Share links encode the formula in the URL hash — nothing goes through a server
+- Nine export formats plus four export menus (image / code / escape / share)
+
+![Editor](docs/img/editor.png)
+
+## Features
+
+### Quick tools
+
+Ten tiles above the input: **common symbols / Greek / fractions & calculus / roots & scripts / limits & logs / trigonometry /
+integrals / large operators / brackets & floors / matrices**.
+
+- Each tile icon is a live-typeset representative formula, not an image
+- Hovering a tile expands its symbol panel **4px below**, grouped exactly like the palette data (e.g. Greek → lower case 30 / upper case 11); it collapses when the pointer leaves
+- Every symbol has a ☆ in its corner to save it to favourites; clicking the symbol inserts it at the caret
+- The tile strip scrolls horizontally with the mouse wheel (vertical wheel is translated), so the right-most tiles are reachable
+
+![Quick tools](docs/img/hover.png)
+
+### Templates
+
+Ten template tiles: **algebra / geometry / inequalities / integrals / matrices / trigonometry / statistics / sequences /
+physics / chemistry** — hover to expand and insert a ready-made snippet (quadratic roots, law of cosines, AM-GM,
+binomial theorem, variance, geometric series, Schrödinger equation, chemical equations …).
+
+![Templates](docs/img/templates.png)
+
+### Format row
+
+A separate row below the tiles, divided by a rule, with eight equal 62px icon buttons:
+
+| Button | What it does |
+| --- | --- |
+| Colour | Palette icon + colour picker; picking a colour wraps the selection in `\textcolor{#hex}{…}` |
+| Font | Roman / bold / italic / underline / sans / blackboard / calligraphic / fraktur, each rendered in that font inside the menu |
+| Size | Nine steps from tiny to huge, each rendered at that size inside the menu |
+| Environment | align / aligned / gathered / cases / split / array / eqnarray, plus "none" (strips the outer environment); wraps the selection in `\begin{…}…\end{…}` |
+| Clear | Empties the source |
+| Undo | Undo the previous edit (keystrokes within 400 ms merge, up to 120 steps) |
+| Import | Reads `.tex` / `.txt` |
+| Favourite | Saves the current formula to favourites |
+
+With a selection the text is wrapped; without one an empty shell is inserted and the caret placed inside.
+
+### Favourites
+
+The fifth tab; every favourite is a card:
+
+- **Title** ("Untitled formula" by default, click to rename), **timestamp**, **rendered preview**, **LaTeX source** (click to copy)
+- **Insert / Copy / Delete** buttons
+- A search box filters by **title or source**
+- The cap defaults to **10** (Settings → Favourites limit, 1–50); the oldest entry is dropped beyond it
+
+![Favourites](docs/img/favourites.png)
+
+### Output
+
+The export bar sits at the top of the preview column, with four menus:
+
+| Menu | Options |
+| --- | --- |
+| Image | SVG / PNG / JPG (3× scale) |
+| Code | LaTeX, AsciiMath, Typst, SVG Code, HTML inline, HTML display, MathML, MathML (mml:), MathML (m:), MathML (attr:), OMML |
+| Escape | Escaped backslash, `$…$`, `$$…$$`, `\(…\)`, `\[…\]`, JSON string |
+| Share | Copy the share link (`#tex=` encoded — opening it restores the formula) |
+
+AsciiMath and Typst are produced by a real TeX parser and OMML by converting the MathML DOM into Word's formula structure — not by copying the LaTeX source.
+
+The canvas background follows the theme: white in the light theme, black in the dark theme (transparent / white / dark can still be picked manually).
+
+### Recognition
+
+- **Image OCR**: drop, paste or pick an image; the configured model returns LaTeX and inserts it
+- **Document OCR**: renders each PDF page and recognises it page by page; when done you can **download Word / LaTeX / Markdown**, and results from the last 15 days can be downloaded again without using quota
+
+![Document OCR](docs/img/doc-ocr.png)
+
+### Interface
+
+- **125%** scale by default, adjustable 100%–200%; narrow panels switch to a compact layout (tabs wrap, actions become icons, panels scroll internally)
+- Light / dark slider (sun / moon icons), system default
+- Language menu: 简体中文 / 繁體中文 / English (traditional Chinese is derived from the simplified dictionary on the fly)
+
+![Settings](docs/img/settings.png)
+
+## Install
+
+The plugin is normally mounted from a **local directory** (`link:` dependency), and it is also available on npm:
+
+```bash
+# local directory
+git clone https://github.com/jiahui-huang1/dsh-latex-formula-editor.git
+pnpm dsh plugin add ./dsh-latex-formula-editor
+
+# or from npm
+pnpm dsh plugin add dsh-latex-formula-editor
+```
+
+Then enable **LaTeX Formula Editor** in the DSH sidebar (entry id `latex-editor`). Restart DSH after changing the plugin.
+
+## Layout
+
+```
+index.js                Host half: static asset routes, recognition endpoint, settings persistence, latex_formula tool
+client.js               Client entry: registers the sidebar entry (sidebar.panellist) and the main panel (main)
+lib/
+ ├─ 00-core.js           namespace, i18n, settings store, UI primitives, icons
+ ├─ 10-latex.js          symbol palette / templates / parser / source utilities
+ ├─ 20-render.js         MathJax rendering, nine export formats, PDF writer
+ ├─ 30-visual.js         legacy symbol / template panels and structure tree
+ ├─ 35-tiles.js          quick-tool and template tiles, favourites, export menus
+ ├─ 40-recognition.js    recognition backends (harness model / OpenAI-compatible endpoint)
+ ├─ 45-convert.js        TeX → AsciiMath / Typst, MathML → OMML
+ ├─ 50-app.js            main UI: editor, preview, export, history, share
+ ├─ 56-recognition-panels.js  image and document OCR panels
+ ├─ 60-settings-help.js  settings and help page
+ └─ 90-skin.js           corporate-clean skin and theme tokens
+vendor/                 MathJax 3.2.2 and PDF.js (shipped with the plugin)
+```
+
+## Settings
+
+- **Editor**: UI scale (125% default), source font size, word wrap, formula numbering, favourites limit
+- **Recognition**: `auto` prefers the harness model; otherwise fill in an OpenAI-compatible endpoint (URL / model / key)
+- Rendering and export are fully offline; only OCR sends the image to your backend
+- Settings live in `<DSH_HOME>/latex-editor/settings.json`
+
+## Requirements
+
+- DSH ≥ 1.0 (Cordis plugin spec: `dsh.bundle.patch` + `dsh.client`)
+- No build step on the browser side; MathJax and PDF.js ship with the plugin
+
+## Licence
+
+MIT

package/README.md

@@ -1,41 +1,147 @@
-# dsh-latex-formula-editor
-
-> LaTeX 公式编辑器 —— DSH 侧栏插件：离线渲染、磁贴取符号、公式模板、收藏夹、图片/文档识别、多格式导出与分享。
-
-![插件界面](docs/img/editor.png)
-
-## 安装
-
-```bash
-# 1. 取仓库
-git clone https://github.com/jiahui-huang1/dsh-latex-formula-editor.git
-# 2. 以本地插件方式安装（DSH 会自动读取 package.json 里的 dsh.bundle.patch / dsh.client）
-pnpm dsh plugin add ./dsh-latex-formula-editor
-```
-
-安装后在 DSH 左侧栏启用 **公式编辑器**（入口 id `latex-editor`）。
-
-## 功能
-
-- **快捷工具**：常用符号 / 希腊字母 / 分数微分 / 根式角标 / 极限对数 / 三角函数 / 积分运算 / 大型运算 / 括号取整 / 数组矩阵，悬停磁贴展开分组符号面板，点击插入光标处
-- **公式模板**：代数 / 几何 / 不等式 / 积分 / 矩阵 / 三角 / 统计 / 数列 / 物理 / 化学，展开即可整条插入
-- **格式行**：取色器、真实字体预览、真实字号预览、环境包裹（align / aligned / gathered / cases / split / array / eqnarray / 无环境）、清空、撤销、导入、收藏
-- **输出**：输出图片（SVG / PNG / JPG）、输出代码（LaTeX / AsciiMath / Typst / SVG Code / HTML 内联与独立 / MathML / MathML mml: / m: / attr: / OMML）、转义（反斜杠、`$…$`、`$$…$$`、`\(…\)`、`\[…\]`、JSON）、分享链接
-- **收藏夹**：标题、时间、渲染结果、源码；可改名 / 复制 / 删除 / 插入；按标题或源码搜索；上限可配（默认 10）
-- **识别**：图片识别（拖拽 / 粘贴）、文档识别（逐页 OCR，支持下载 Word / LaTeX / Markdown，最近 15 天记录可重新下载）
-- **界面**：默认 150% 缩放、浅色/深色主题、简体中文 / 繁體中文 / English
-
-![文档识别](docs/img/doc-ocr.png)
-
-## 配置
-
-设置 → 识别服务：可选 Harness 内置模型或自建 OpenAI 兼容端点；渲染与导出完全离线，仅识别会发送图片。
-
-## 兼容性
-
-- DSH ≥ 1.0（Cordis 插件规范：`dsh.bundle.patch` + `dsh.client`）
-- 浏览器侧无构建步骤，MathJax 3 与 PDF.js 已随插件内置
-
-## 许可
-
-MIT
+# DSH LaTeX 公式编辑器
+
+简体中文 · [English](README.en.md)
+
+[![npm](https://img.shields.io/npm/v/dsh-latex-formula-editor.svg)](https://www.npmjs.com/package/dsh-latex-formula-editor)
+[![topic](https://img.shields.io/badge/topic-dsh--plugin-0e7490.svg)](https://github.com/topics/dsh-plugin)
+
+一个免费开源、可离线使用的 LaTeX 公式编辑器，挂在 DeepSeek Harness Web UI 的**左侧栏**（图标 `Σ`）。
+交互参考 [latexlive.com](https://www.latexlive.com/)，但**全部在自己的机器上运行**：数学渲染用随包分发的
+MathJax，PDF 解析用随包分发的 PDF.js，没有账号、没有额度、也不会上传（除了你自己配置的识别后端）。
+
+- 侧栏入口 → 主面板，五个视图：**编辑器 / 图片识别 / 文档识别 / 收藏夹 / 帮助**
+- LaTeX 实时渲染（MathJax 3.2.2，SVG 输出，离线）
+- 界面缩放默认 **125%**（设置 → 界面缩放可在 100%–200% 之间切换）
+- 浅色 / 深色主题一键切换（默认跟随系统），简体中文 / 繁體中文 / English 三语
+- 分享链接把公式编码进 URL hash，不经过任何服务器
+- 九种导出格式 + 四组导出菜单（图片 / 代码 / 转义 / 分享）
+
+![编辑器](docs/img/editor.png)
+
+## 功能
+
+### 快捷工具
+
+输入区上方是 10 张磁贴：**常用符号 / 希腊字母 / 分数微分 / 根式角标 / 极限对数 / 三角函数 / 积分运算 / 大型运算 / 括号取整 / 数组矩阵**。
+
+- 磁贴图标是按分类实时排版的代表公式，不是图片
+- 悬停磁贴在正下方 **4px** 处展开该分类的符号面板，并按数据里的分组分节（如希腊字母 → 小写字母 30 / 大写字母 11），移开自动收拢
+- 面板里每个符号右上角有 ☆，点一下收藏到收藏夹，点击符号本身插入到光标处
+- 磁贴行支持**滚轮横向滚动**（竖向滚轮自动转成横向），最右侧磁贴可滚到
+
+![快捷工具](docs/img/hover.png)
+
+### 公式模板
+
+10 张模板磁贴：**代数 / 几何 / 不等式 / 积分 / 矩阵 / 三角 / 统计 / 数列 / 物理 / 化学**，悬停展开后整条插入现成模板（求根公式、余弦定理、均值不等式、二项式定理、方差、等比数列求和、薛定谔方程、化学方程式等）。
+
+![公式模板](docs/img/templates.png)
+
+### 格式工具
+
+磁贴行下方用分隔线隔开的独立一行，8 个等宽图标按钮（62px）：
+
+| 按钮 | 说明 |
+| --- | --- |
+| 颜色 | 调色盘图标 + 取色器，选色即把选中文字包进 `\textcolor{#hex}{…}` |
+| 字体 | 正体 / 加粗 / 斜体 / 下划线 / 无衬线 / 黑板粗体 / 手写体 / 德文尖角体，下拉里每项用该字体真实渲染 |
+| 字号 | 极小 → 巨无霸九档，下拉里每项用该字号真实渲染 |
+| 环境 | align / aligned / gathered / cases / split / array / eqnarray，以及「无环境」（拆掉最外层环境）；选中即包 `\begin{…}…\end{…}` |
+| 清空 | 清空源码区 |
+| 撤销 | 撤销上一步（连续输入 400ms 合并为一步，最多 120 步） |
+| 导入 | 读取 `.tex` / `.txt` |
+| 收藏 | 把当前公式存进收藏夹 |
+
+有选中文字就包裹选中内容，没有则插入空壳并把光标放进去。
+
+### 收藏夹
+
+顶部第五个页签，每条收藏是一张卡片：
+
+- **标题**（默认「未命名公式」，点击即可改名）、**收藏时间**、**渲染结果**、**LaTeX 源码**（点击即复制）
+- **插入 / 复制 / 删除** 三个按钮
+- 顶部搜索框可按**标题或源码**检索
+- 数量上限默认 **10**，在 设置 → 收藏夹上限 调整（1–50），超出时丢弃最旧的一条
+
+![收藏夹](docs/img/favourites.png)
+
+### 输出区域
+
+导出条在预览区顶部，四组菜单：
+
+| 菜单 | 选项 |
+| --- | --- |
+| 输出图片 | SVG / PNG / JPG（3× 倍率） |
+| 输出代码 | LaTeX、AsciiMath、Typst、SVG Code、HTML 行内、HTML 独立、MathML、MathML(mml:)、MathML(m:)、MathML(attr:)、OMML |
+| 转义 | 反斜杠转义、`$…$`、`$$…$$`、`\(…\)`、`\[…\]`、JSON 字符串 |
+| 分享 | 复制分享链接（`#tex=` 编码，打开即回填公式） |
+
+AsciiMath / Typst 由内置 TeX 解析器真实转换，OMML 由 MathML DOM 转换为 Word 公式结构，不是直接复制 LaTeX。
+
+预览画布底色随主题自动切换：浅色主题白底、深色主题黑底（透明 / 白底 / 深色仍可手动覆盖）。
+
+### 识别
+
+- **图片识别**：拖拽、粘贴或选择图片，调用你配置的模型识别为 LaTeX 并插入编辑器
+- **文档识别**：PDF 逐页渲染后识别，可挑页；完成后可**下载 Word / LaTeX / Markdown**，最近 15 天的识别记录可重新下载（不消耗额度）
+
+![文档识别](docs/img/doc-ocr.png)
+
+### 界面
+
+- 默认 **125%** 缩放，100%–200% 可调；窄面板自动进入紧凑布局（页签换行、图标化动作、面板内滚动）
+- 浅色 / 深色主题滑块（太阳 / 月亮图标），默认跟随系统
+- 语言菜单：简体中文 / 繁體中文 / English，繁体由简体词表实时转换
+
+![设置](docs/img/settings.png)
+
+## 安装
+
+本插件通过**本地目录**挂载到 DSH profile（`link:` 依赖），也可以从 npm 安装：
+
+```bash
+# 方式一：本地目录
+git clone https://github.com/jiahui-huang1/dsh-latex-formula-editor.git
+pnpm dsh plugin add ./dsh-latex-formula-editor
+
+# 方式二：npm 包
+pnpm dsh plugin add dsh-latex-formula-editor
+```
+
+安装后在 DSH 左侧栏启用 **公式编辑器**（入口 id `latex-editor`）。修改插件后重启 DSH 即可生效。
+
+## 目录结构
+
+```
+index.js                 Host 半：静态资源路由、识别接口、设置持久化、latex_formula 工具
+client.js                客户端入口：注册侧栏入口（sidebar.panellist）与主面板（main）
+lib/
+ ├─ 00-core.js           命名空间、i18n、设置存储、UI 原子组件、图标
+ ├─ 10-latex.js          符号表 / 模板 / 解析器 / 源码工具（纯逻辑）
+ ├─ 20-render.js         MathJax 渲染、九种导出格式、PDF 生成
+ ├─ 30-visual.js         旧版符号面板 / 模板面板 / 结构树（新面板见 35-tiles）
+ ├─ 35-tiles.js          快捷工具与公式模板磁贴、收藏夹、导出菜单
+ ├─ 40-recognition.js    识别后端（Harness 模型 / OpenAI 兼容端点）
+ ├─ 45-convert.js        TeX → AsciiMath / Typst、MathML → OMML
+ ├─ 50-app.js            主界面：编辑器、预览、导出、历史、分享
+ ├─ 56-recognition-panels.js  图片识别与文档识别界面
+ ├─ 60-settings-help.js  设置面板与帮助页
+ └─ 90-skin.js           企业简洁风皮肤与主题变量
+vendor/                  MathJax 3.2.2 与 PDF.js（随包分发）
+```
+
+## 设置
+
+- **编辑器**：界面缩放（默认 125%）、源码字号、自动换行、公式编号、收藏夹上限
+- **识别**：`auto` 优先用 Harness 模型；也可填 OpenAI 兼容端点（URL / 模型 / Key）
+- 渲染与导出完全离线，只有识别会把图片发给你配置的后端
+- 设置保存在本机 `<DSH_HOME>/latex-editor/settings.json`
+
+## 兼容性
+
+- DSH ≥ 1.0（Cordis 插件规范：`dsh.bundle.patch` + `dsh.client`）
+- 浏览器侧没有构建步骤，MathJax 与 PDF.js 已随插件内置
+
+## 许可
+
+MIT