@jaxzhou/dsh-file-explorer 0.1.3 → 0.1.5

package/README.md

@@ -20,11 +20,14 @@ dsh --profile web
 
 ## Demo
 
-[![The Files tab beside Chat and Trajectory: a workspace tree on the left, and
-on the right a preview that highlights source, renders Markdown and JSON, and
-offers a Rendered/Source toggle](media/demo.gif)](media/demo.mp4)
+[![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)
 
-*30 seconds — click for the full-quality 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.
 
 ## What you get
 
@@ -41,8 +44,8 @@ The right pane picks each tab's body from the file:
 
 | Category | Preview |
 |---|---|
-| **Markdown** | Rendered GFM — headings, tables, task lists, quotes, math, footnotes, highlighted code fences — with a **Source** toggle, and **Export PDF** |
-| **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 **Export PDF** |
+| **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 |
+| **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 |
@@ -51,10 +54,18 @@ The right pane picks each tab's body from the file:
 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. A rendered Markdown or HTML file also carries **Export PDF**,
-which hands the page to the browser's print dialog: every browser offers "Save as
-PDF" there, and its own layout engine keeps the text as text rather than
-rasterising the page the way a canvas-based PDF library would.
+Markdown source.
+
+A rendered Markdown or HTML document also carries **Export**, which **downloads a
+file directly** — no print dialog — in either of two formats:
+
+| Format | What it is |
+|---|---|
+| **PDF** | A picture of the page, laid out as A4 and sliced to fit. The text in it is not selectable. That is deliberate: a text-mode PDF of a Chinese document would need a CJK font embedded in the plugin, which is megabytes for a preview tool |
+| **Word** (`.docx`) | A real Word document: headings, lists, tables, code and images, with the text still text — editable, searchable, and rendered with Word's own fonts. Chinese included |
+
+A document's own local assets come with it: the images a Markdown file references
+beside it, and the images and stylesheets an HTML file links to.
 
 ## Requirements
 
@@ -137,12 +148,20 @@ restart the profile.
   an older tab stays open and reads again when you return to it.
 - **One root.** The tree is rooted at the session's working directory, and the
   Host refuses directory listings outside the workspace root.
-- **Markdown has no workspace vocabulary.** Relative image paths and file
-  mentions stay inert; only absolute `http(s)` images load.
+- **Markdown pulls in the images beside it.** A destination relative to the document
+  is read through the same workspace reader the file itself came from — up to 24
+  images per document and 8 MiB each. A file mention in inline code, a remote URL,
+  and an absolute path are left to the renderer's own rules: the first stays inert,
+  the second loads directly, and the third is not fetched.
 - **HTML previews do not resolve relative assets.** A page drawn from a Blob
   document has no base to resolve its own `style.css` or images against, so only
-  absolute URLs load there too. An export prints the page as it renders without
-  its scripts, which a static PDF has no use for anyway.
+  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
+  Word instead when the text has to stay text.
+- **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.
 
 ## Contributing
 

package/README.zh.md

@@ -20,10 +20,12 @@ dsh --profile web
 
 ## 演示
 
-[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是预览——可高亮源码、渲染
-Markdown 与 JSON，并提供「预览/源码」切换](media/demo.gif)](media/demo.mp4)
+[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是渲染后的 Markdown 文档，
+工具栏上带复制、源码与导出 PDF](media/demo.gif)](media/demo.mp4)
 
-*30 秒录屏 —— 点击可打开完整画质的 MP4。*
+*15 秒录屏 —— 点击可打开完整画质的 MP4。* 一个小数学工作区：渲染后的讲义文档
+（含表格）、切到 **源码** 看它背后的 Markdown、在旁边用另一个标签打开第二份文档，
+最后用 **导出 PDF** 把页面交给浏览器的打印对话框。
 
 ## 能做什么
 
@@ -37,8 +39,8 @@ Markdown 与 JSON，并提供「预览/源码」切换](media/demo.gif)](media/d
 
 | 类别 | 预览 |
 |---|---|
-| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、高亮的代码围栏 —— 并带 **源码** 切换与 **导出 PDF** |
-| **HTML** | 在沙箱 iframe 中当作页面绘制：文件自己的 CSS 生效，其脚本运行在不透明源（opaque origin）里，无法触达本应用。带 **源码** 切换与 **导出 PDF** |
+| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、引用文件旁的图片、高亮的代码围栏 —— 并带 **源码** 切换与 **导出** 菜单 |
+| **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>` 绘制，其中的脚本不会执行 |
@@ -46,9 +48,18 @@ Markdown 与 JSON，并提供「预览/源码」切换](media/demo.gif)](media/d
 
 文本预览在空格处折行、保持单词完整；图片读取完整字节。每一种文本预览在窗格工具栏
 里都有 **复制** 按钮，复制的是文件自身的文本——渲染态的 Markdown 复制的是它的
-Markdown 源码。渲染态的 Markdown 与 HTML 还带 **导出 PDF**：它把页面交给浏览器的
-打印对话框，那里每个浏览器都提供「另存为 PDF」，而排版由浏览器自己的引擎完成
-——文字仍是文字，不像基于 canvas 的 PDF 库那样把整页栅格化。
+Markdown 源码。
+
+渲染态的 Markdown 与 HTML 还带 **导出** 菜单，**直接下载文件**（不走打印对话框），
+两种格式：
+
+| 格式 | 说明 |
+|---|---|
+| **PDF** | 页面的图像：按 A4 排版并分页切分。其中的文字**不可选中**。这是刻意的：中文文档若用文本模式生成 PDF，就必须在插件里内嵌 CJK 字体——对一个预览工具来说是好几 MB |
+| **Word**（`.docx`） | 真正的 Word 文档：标题、列表、表格、代码与图片都在，文字仍是文字——可编辑、可搜索，中文交给 Word 自己的字体渲染 |
+
+文档自带的本地资源会一起带上：Markdown 文件旁边引用的图片，以及 HTML 文件链接的
+图片与样式表。
 
 ## 环境要求
 
@@ -122,11 +133,17 @@ profile。
   回到它时会重新读取。
 - **单一根目录**：目录树以会话工作目录为根，Host 本身也拒绝读取工作区根之外的
   目录列表。
-- **Markdown 不解析工作区词汇**：相对图片路径与文件提及保持原样，只有绝对
-  `http(s)` 图片会加载。
+- **Markdown 会读入它旁边的图片**：相对文档的图片路径会通过与文件本身相同的
+  工作区读取通道加载——上限为每篇 24 张、单张 8 MiB。行内代码里的文件提及、远程
+  URL、绝对路径则交给渲染器自己的规则：第一个保持原样，第二个直接加载，第三个
+  不会去读。
 - **HTML 预览不解析相对资源**：由 Blob 文档绘制出的页面没有可用来解析自身
-  `style.css` 或图片的 base，所以同样只有绝对 URL 能加载。导出时按渲染结果打印，
-  且不带脚本——静态 PDF 本来也用不上脚本。
+  `style.css` 或图片的 base，所以预览里只有绝对 URL 能加载。**导出时会解析**——
+  写出的文件来自一份被补齐成自包含的副本——所以可能有「预览里看不到图，导出里
+  有图」的情况。
+- **PDF 里的文字是图像**，无法选中或搜索。需要文字可编辑时请导出 Word。
+- **超长文档会在 60 页 PDF 处截断**，单张超过 8 MiB 的图片会被跳过；写在这里是因为
+  静默截断会被误认为完整导出。
 
 ## 参与开发