@jaxzhou/dsh-file-explorer 0.1.5 → 0.1.7

package/README.md

@@ -10,8 +10,9 @@ English | [中文](README.zh.md)
 
 A **Files** tab for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness),
 beside **Chat** and **Trajectory**: the session workspace as a tree, and a preview
-that adapts to what the file is — rendered Markdown, a JSON tree, highlighted
-source, an image, or plain text. Read-only, no configuration, nothing stored.
+that adapts to what the file is — rendered Markdown with its diagrams, a page of
+HTML, a JSON tree, highlighted source, an image, a PDF, or an unpacked Word, Excel
+or PowerPoint document. Read-only, no configuration, nothing stored.
 
 ```sh
 dsh plugin --profile web add @jaxzhou/dsh-file-explorer
@@ -21,13 +22,17 @@ dsh --profile web
 ## Demo
 
 [![The Files tab beside Chat and Trajectory: a workspace tree on the left, and a
-rendered Markdown document on the right whose toolbar carries Copy, Source and
-Export PDF](media/demo.gif)](media/demo.mp4)
+rendered Markdown document on the right](media/demo.gif)](media/demo.mp4)
 
 *15 seconds — click for the full-quality MP4.* A primary-school maths workspace: a
 lesson document rendered with its tables, the **Source** toggle showing the
-Markdown behind it, a second document open beside it in its own tab, and **Export
-PDF**, which hands the page to the browser's print dialog.
+Markdown behind it, a second document open beside it in its own tab, and an export
+of it to PDF.
+
+**The recording is an older build than the list below.** It predates Mermaid
+diagrams, the PDF and Office previews, and downloading a file from the pane at
+all, and it still shows an export handing the page to the browser's print dialog —
+which no export does now.
 
 ## What you get
 
@@ -44,20 +49,41 @@ The right pane picks each tab's body from the file:
 
 | Category | Preview |
 |---|---|
-| **Markdown** | Rendered GFM — headings, tables, task lists, quotes, math, footnotes, images referenced beside the file, highlighted code fences — with a **Source** toggle and an **Export** menu |
+| **Markdown** | Rendered GFM — headings, tables, task lists, quotes, math, footnotes, images referenced beside the file, highlighted code fences, and **Mermaid diagrams** — with a **Source** toggle and an **Export** menu |
 | **HTML** | Drawn as a page in a sandboxed frame: the file's own CSS applies, and its scripts run in an opaque origin that cannot reach this application. With a **Source** toggle and an **Export** menu |
 | **JSON** | A collapsible tree with per-value copy, and the same toggle |
 | **Source code** | Syntax highlighting, line numbers, and a copy button for 24 grammars: TypeScript/JavaScript, shell, Python, Ruby, Go, Rust, Java, C, C++, C#, Kotlin, Swift, PHP, YAML, TOML, INI, HTML, CSS, SCSS, Less, SQL, XML, Lua, MDX |
 | **Images** | PNG, JPEG, GIF, WebP, AVIF, BMP, ICO and SVG, drawn to the pane. An SVG goes through `<img>`, so its scripts never run |
-| **Anything else** | Numbered plain text — an unmapped suffix (`.vue`, `.proto`, `.txt`) stays plain rather than guessing a wrong grammar |
+| **PDF** | Drawn by the browser's own PDF reader, from the file's bytes — so its text is real text |
+| **Word, Excel, PowerPoint** | `.docx`, `.xlsx` and `.pptx` unpacked in the page: a document's headings, lists, tables, pictures and code; a workbook's sheets as a grid, with the dates it stores as numbers shown as dates; a deck's slides as an outline of their text and pictures |
+| **Anything else** | Numbered plain text — an unmapped suffix (`.vue`, `.proto`, `.txt`) stays plain rather than guessing a wrong grammar. The legacy binary Office formats (`.doc`, `.xls`, `.ppt`) are not previewed: the pane says so and offers the download |
+
+A **Mermaid** code fence (` ```mermaid `) is a diagram, not source, so the pane
+draws it: flowcharts, sequence diagrams, state, class, ER, gantt, pie and the
+rest of what Mermaid 11 understands. The drawing is a picture everywhere it
+appears — the preview, the PDF page, and the Word document all carry the same
+image — so what you see is what exports. A diagram Mermaid cannot parse keeps its
+source, with the failure named above it.
 
 Text previews wrap at their spaces and keep every word whole; an image reads its
-complete bytes. Every text body carries a **Copy** control in the pane's toolbar,
-which copies the file's own text — a rendered Markdown document copies its
-Markdown source.
+complete bytes.
+
+Every preview carries one **Export** button in the pane's toolbar. Its first row
+is **Download**, which saves the file itself — not a conversion of it — so that row
+is there for every kind of file, including the ones this pane will not draw. **Its
+size is not a limit**: a download is read a window at a time rather than all at
+once, so a file larger than a preview can hold still saves normally — a 260 MB
+release tarball included. Up to 32 MiB it goes quietly to the browser's downloads;
+past that it asks where to put it and streams there, which keeps the memory it
+costs flat however large the file is. Several downloads run at once, each with its
+own row, its own progress and its own **Cancel**, and one failing leaves the
+others alone.
+
+Every text body carries **Copy**, which copies the file's own text — a rendered
+Markdown document copies its Markdown source.
 
-A rendered Markdown or HTML document also carries **Export**, which **downloads a
-file directly** — no print dialog — in either of two formats:
+A rendered Markdown or HTML document adds two rows to that menu — **PDF** and
+**Word** — and each **downloads a file directly**, with no print dialog:
 
 | Format | What it is |
 |---|---|
@@ -127,6 +153,11 @@ restart the profile.
   state lives in memory and is discarded with the session.
 - **Inert Host half.** The package's Node side registers no service, tool, prompt
   section, or event.
+- **Diagrams are drawn in the page.** Mermaid is bundled into the plugin and runs
+  locally; drawing a diagram fetches nothing from anywhere.
+- **Office documents are unpacked in the page.** A `.docx`, `.xlsx` or `.pptx` is
+  read here, by this plugin's own reader; nothing about it leaves the browser. A
+  PDF is handed to the browser's reader as a local blob URL.
 - **HTML runs sandboxed.** A previewed page's scripts execute in an opaque origin,
   which cannot read this application's DOM, storage, or session; an exported page
   is printed with its scripts removed. An SVG draws through `<img>`, so its scripts
@@ -158,8 +189,32 @@ restart the profile.
   absolute URLs load there. **An export does resolve them** — the file it writes is
   read from a copy that has been made to stand alone — so a document can export
   with pictures it does not show in the preview.
-- **A PDF's text is a picture.** Nothing in it can be selected or searched. Export
+- **An exported PDF's text is a picture.** Nothing in it can be selected or
+  searched — a *previewed* PDF is the browser's own reader, where it can. Export
   Word instead when the text has to stay text.
+- **A Mermaid diagram is a picture too.** It is drawn once, to a PNG, for the
+  preview and for both exports — so its labels are not selectable, and it is
+  always drawn on white, because a PDF page and a Word document are white and a
+  diagram drawn for a dark pane would be invisible on them. Drawing supports the
+  diagram types Mermaid 11 carries; a malformed one keeps its source and names
+  the failure above it.
+- **An Office preview is content, not layout.** A `.docx` shows its headings,
+  text, lists, tables and pictures; a `.xlsx` shows its cells' values; a `.pptx`
+  shows each slide's text and pictures. What is *not* there is everything that
+  needs a layout engine and the fonts the file names: colours and themes, column
+  widths, page breaks, headers and footers, charts, SmartArt, and animations.
+  Formulas show the value the file cached, not a recalculation.
+- **Only the OOXML formats are read.** `.doc`, `.xls` and `.ppt` are the older
+  binary container, which this pane does not parse — it says so and offers the
+  download instead.
+- **A preview is bounded by one complete-file read**, 32 MiB by default in the
+  shipped Web composition: a larger PDF or Office package reports the refusal
+  rather than being shown cut. A **download** is not bounded that way — it pages
+  through the file — so something too large to preview can still be saved.
+- **A large download goes through the browser's save dialog.** Past 32 MiB the
+  bytes stream into a file you pick, which is what keeps the memory cost flat; a
+  browser without that API collects the file first, so a very large download
+  there costs its own size in memory.
 - **Long documents are cut at 60 PDF pages**, and an image past 8 MiB is left out;
   both are stated here because a silent cut reads as a complete export.
 

package/README.zh.md

@@ -10,8 +10,9 @@
 
 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 增加一个
 **文件** 标签，与 **对话**、**轨迹** 并列：左侧是会话工作区的目录树，右侧的预览
-会按文件本身决定形态 —— 渲染后的 Markdown、JSON 树、语法高亮源码、图片，或纯
-文本。只读、无需配置、不落任何数据。
+会按文件本身决定形态 —— 渲染后的 Markdown（含图表）、HTML 页面、JSON 树、语法
+高亮源码、图片、PDF，以及解包后的 Word / Excel / PowerPoint 文档。只读、无需配置、
+不落任何数据。
 
 ```sh
 dsh plugin --profile web add @jaxzhou/dsh-file-explorer
@@ -20,12 +21,15 @@ dsh --profile web
 
 ## 演示
 
-[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是渲染后的 Markdown 文档，
-工具栏上带复制、源码与导出 PDF](media/demo.gif)](media/demo.mp4)
+[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是渲染后的 Markdown 文档](media/demo.gif)](media/demo.mp4)
 
 *15 秒录屏 —— 点击可打开完整画质的 MP4。* 一个小数学工作区：渲染后的讲义文档
 （含表格）、切到 **源码** 看它背后的 Markdown、在旁边用另一个标签打开第二份文档，
-最后用 **导出 PDF** 把页面交给浏览器的打印对话框。
+最后把它导出为 PDF。
+
+**录屏来自比下面更早的版本。** 它早于 Mermaid 图表、PDF 与 Office 预览，也早于
+「在窗格里直接下载文件」，其中那次导出仍然把页面交给浏览器的打印对话框 —— 现在的
+导出都不会。
 
 ## 能做什么
 
@@ -39,19 +43,34 @@ dsh --profile web
 
 | 类别 | 预览 |
 |---|---|
-| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、引用文件旁的图片、高亮的代码围栏 —— 并带 **源码** 切换与 **导出** 菜单 |
+| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、引用文件旁的图片、高亮的代码围栏、**Mermaid 图表** —— 并带 **源码** 切换与 **导出** 菜单 |
 | **HTML** | 在沙箱 iframe 中当作页面绘制：文件自己的 CSS 生效，其脚本运行在不透明源（opaque origin）里，无法触达本应用。带 **源码** 切换与 **导出** 菜单 |
 | **JSON** | 可折叠树，每个值可单独复制，同样带 **源码** 切换 |
 | **源码** | 24 种语法的语法高亮、行号与复制按钮：TypeScript/JavaScript、shell、Python、Ruby、Go、Rust、Java、C、C++、C#、Kotlin、Swift、PHP、YAML、TOML、INI、HTML、CSS、SCSS、Less、SQL、XML、Lua、MDX |
 | **图片** | PNG、JPEG、GIF、WebP、AVIF、BMP、ICO、SVG，自动适配窗格。SVG 经 `<img>` 绘制，其中的脚本不会执行 |
-| **其它** | 带行号的纯文本 —— 未映射的后缀（`.vue`、`.proto`、`.txt`）保持纯文本，而不是猜测一个错误的高亮 |
+| **PDF** | 交由浏览器自带的 PDF 阅读器绘制，用的是文件自身的字节 —— 因此其中的文字是真文字 |
+| **Word / Excel / PowerPoint** | `.docx`、`.xlsx`、`.pptx` 在页面内解包：文档的标题、列表、表格、图片与代码；工作簿按工作表显示为网格，并以日期显示它按数字存储的日期；演示文稿按幻灯片显示其文字与图片的提纲 |
+| **其它** | 带行号的纯文本 —— 未映射的后缀（`.vue`、`.proto`、`.txt`）保持纯文本，而不是猜测一个错误的高亮。旧版二进制 Office 格式（`.doc`、`.xls`、`.ppt`）不做预览：窗格会说明原因并提供下载 |
+
+**Mermaid** 代码围栏（` ```mermaid `）是图表而不是源码，窗格会把它画出来：
+流程图、时序图、状态图、类图、ER 图、甘特图、饼图，以及 Mermaid 11 支持的其它
+类型。它在出现的每一处都是图像 —— 预览、PDF 页面、Word 文档携带的是同一张图 ——
+所见即所得。Mermaid 无法解析的图表会保留源码，并在其上方说明失败原因。
+
+文本预览在空格处折行、保持单词完整；图片读取完整字节。
+
+每种预览的窗格工具栏里只有**一个导出按钮**，菜单第一行是 **下载**，保存的是文件本身
+而不是它的某种转换 —— 因此这一行对**所有**文件类型都在，包括本窗格不绘制的那些。
+**它不受文件大小限制**：下载按窗口逐段读取而不是一次性读完，所以比预览上限更大的
+文件也能正常保存——260 MB 的发布包也不例外。32 MiB 以内静默存到浏览器的下载目录；
+超过则询问保存位置并直接流式写入，因此内存占用与文件大小无关。可以同时进行多个下载，
+每个都有自己的进度行和 **取消**，其中一个失败不影响其余。
 
-文本预览在空格处折行、保持单词完整；图片读取完整字节。每一种文本预览在窗格工具栏
-里都有 **复制** 按钮，复制的是文件自身的文本——渲染态的 Markdown 复制的是它的
+每一种文本预览还有 **复制**，复制的是文件自身的文本——渲染态的 Markdown 复制的是它的
 Markdown 源码。
 
-渲染态的 Markdown 与 HTML 还带 **导出** 菜单，**直接下载文件**（不走打印对话框），
-两种格式：
+渲染态的 Markdown 与 HTML 会在该菜单里再加两行 —— **PDF** 与 **Word** ——
+各自 **直接下载文件**（不走打印对话框）：
 
 | 格式 | 说明 |
 |---|---|
@@ -115,6 +134,10 @@ profile。
   Host 的文件系统决定。插件自身不持有文件权限、不做路径解析、不接触凭据。
 - **不落数据**：不写磁盘、不写会话日志；视图状态保存在内存中，随会话一起释放。
 - **Host 半边是空实现**：包的 Node 侧不注册任何服务、工具、提示词片段或事件。
+- **图表在页面内绘制**：Mermaid 打包在插件里、在本地运行；绘制图表不会向任何地方
+  发起请求。
+- **Office 文档在页面内解包**：`.docx`、`.xlsx`、`.pptx` 由本插件自己的读取器在本地
+  解析，内容不会离开浏览器。PDF 则以本地 blob URL 交给浏览器自带的阅读器。
 - **HTML 在沙箱中运行**：预览页面的脚本执行于不透明源，无法读取本应用的 DOM、
   存储或会话；导出时会先剥除脚本再打印。SVG 经 `<img>` 绘制，脚本完全不执行。
 
@@ -141,7 +164,23 @@ profile。
   `style.css` 或图片的 base，所以预览里只有绝对 URL 能加载。**导出时会解析**——
   写出的文件来自一份被补齐成自包含的副本——所以可能有「预览里看不到图，导出里
   有图」的情况。
-- **PDF 里的文字是图像**，无法选中或搜索。需要文字可编辑时请导出 Word。
+- **导出的 PDF 里文字是图像**，无法选中或搜索（**预览** PDF 用的是浏览器自带的
+  阅读器，文字可选）。需要文字可编辑时请导出 Word。
+- **Mermaid 图表同样是图像**：它只绘制一次（PNG），供预览与两种导出共用 —— 因此
+  其中的标签不可选中，且始终以白底绘制：PDF 页面与 Word 文档都是白底，为深色窗格
+  绘制的图在它们上面会看不见。绘制范围是 Mermaid 11 支持的图表类型；语法错误的
+  图表会保留源码，并在上方说明失败原因。
+- **Office 预览是内容，不是排版**：`.docx` 显示标题、正文、列表、表格与图片；
+  `.xlsx` 显示单元格的值；`.pptx` 显示每页的文字与图片。**没有**的是所有需要排版
+  引擎和文件所指定字体的东西：颜色与主题、列宽、分页、页眉页脚、图表、SmartArt、
+  动画。公式显示文件缓存的值，不做重算。
+- **只读取 OOXML 格式**：`.doc`、`.xls`、`.ppt` 是更早的二进制容器，本窗格不解析
+  —— 会说明这一点并提供下载。
+- **预览受「完整读取」上限约束**：官方 Web 组合默认 32 MiB，超过的 PDF 或 Office
+  包会报告被拒绝，而不是截断后显示。**下载不受此限制** —— 它按窗口分页读取 —— 所以
+  预览不了的文件仍然可以保存。
+- **大文件下载会走浏览器的保存对话框**：超过 32 MiB 时字节流式写入你选择的文件，
+  内存占用因此恒定；不支持该 API 的浏览器会先收集文件，此时超大下载会占用等量内存。
 - **超长文档会在 60 页 PDF 处截断**，单张超过 8 MiB 的图片会被跳过；写在这里是因为
   静默截断会被误认为完整导出。