@weniatall/dsh-file-viewer 0.2.9 → 0.2.10

package/README.md

@@ -82,7 +82,10 @@ dsh plugin --profile web add <release-tgz-url>
       #   label: 共享数据盘
       # Windows 示例：
       # - D:/Notes
+    # 在线预览（图片/PDF/表格/文档）单文件上限，默认 20 MB
     maxBytes: 20971520
+    # 下载到本地单文件上限，默认 100 MB
+    maxDownloadBytes: 104857600
 ```
 
 配置后：
@@ -92,7 +95,24 @@ dsh plugin --profile web add <release-tgz-url>
 - 为保持向后兼容，原有的 `extraRoots` 与 `safeAccessPaths` 别名依然有效并会自动合并；
 - **Web 界面动态配置与双重持久化**：可在输入框工具栏文件查看器入口或文件树顶部的「安全访问路径设置」弹窗中直接添加、查看或删除安全路径，保存后会自动双重持久化写入当前 Profile 配置（`cordis.patch.yml`）与本地文件（`~/.dsh/file-viewer/settings.json`），DSH 服务重启后配置稳定保留不丢失。
 
-插件不注册任何 HTTP 路由，全部通过 `trusted-host` 权限的 RPC 通道通信，从而复用 DSH `/api` 的浏览器信任围栏（Host/Origin 校验、DNS rebinding 防护）。二进制文件经 RPC 取回后在浏览器侧生成 blob URL，默认单文件上限 20 MB。
+### 下载与预览使用两套上限
+
+下载上限（`maxDownloadBytes`，默认 100 MB）与在线预览上限（`maxBytes`，默认 20 MB）是**独立**的两个值，因为两条通道的代价不同：
+
+- **预览**把整个文件以 base64 塞进 JSON 响应，浏览器还要再 `atob` 解码一次；20 MB 的文件已经会产生约 27 MB 的传输文本，因此这条通道刻意保持小预算；
+- **下载**由浏览器直接消费，或由桌面端流式读取后交给保存流程，不需要解码进页面，因此可以给到 100 MB。
+
+两个上限都支持通过配置调整；把 `maxDownloadBytes` 调大时，宿主仍需一次性读出该文件，请按可用内存权衡。
+
+### 下载在不同宿主中的行为
+
+插件在 `/api` 之下注册了一个带鉴权的流式下载端点，并让客户端按宿主能力选择传输方式：
+
+- **浏览器**：先发一次 `HEAD` 预检（超限直接提示「文件超过下载限制（上限 100MB）」，不会产生一条失败的下载记录），随后把鉴权后的 URL 交给浏览器原生下载管理器。进度、暂停、续传与保存位置都由浏览器负责，页面内存不随文件大小增长；
+- **桌面端（Electron）**：桌面外壳没有浏览器的下载面板，因此改用 `fetch` 流式读取，并在抽屉内实时显示百分比进度（如 `正在下载 dataset.zip (45% - 45.2 MB / 100.0 MB)...`），完成后交给保存流程；
+- **兜底**：流式端点不可用（旧宿主或路由被占用）时，自动回退到既有的 RPC `bytes` 通道，功能不缺失。
+
+下载端点的错误响应只回传机器可读的原因码（如 `FS_TOO_LARGE`、`too-large`），不会回显宿主的绝对路径；这与 RPC 通道既有的「绝不泄露路径」约定一致。
 
 ## 未知后缀文件的文本识别
 

package/lib/client.js

@@ -299,7 +299,7 @@ window.__ModuleLoader__.load({
     const inject = ["slots", "connection", "workspaces"];
 
     const css = `
-      .fv-scrim{position:absolute;inset:0;z-index:40;display:flex;align-items:stretch;justify-content:flex-end;background:transparent;pointer-events:auto;color-scheme:light dark;animation:fv-fade .16s ease-out}
+      .fv-scrim{position:absolute;inset:0;z-index:40;display:flex;align-items:stretch;justify-content:flex-end;background:transparent;pointer-events:auto;animation:fv-fade .16s ease-out}
       .fv-shell{display:flex;flex-direction:column;width:min(64vw,1100px);min-width:0;min-height:0;overflow:hidden;border-left:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2,var(--dsw-alias-bg-base,#fff));box-shadow:var(--dsw-shadow-lv3);font-family:var(--dsw-font-family);color:var(--dsw-alias-label-primary);animation:fv-slide .2s cubic-bezier(.2,.8,.2,1);transition:width .2s cubic-bezier(.2,.8,.2,1)}
       .fv-shell[data-fullscreen="true"]{width:100vw;border-left:none}
       /* Windows desktop paints the native caption buttons (minimize, maximize,
@@ -424,7 +424,7 @@ window.__ModuleLoader__.load({
       .fv-badge{display:inline-block;padding:0 4px;font-size:10px;font-weight:600;line-height:14px;border-radius:4px;margin-left:4px;flex:none}
       .fv-badge-mod{background:color-mix(in srgb,var(--dsw-alias-state-warning-primary,#d97706) 18%,transparent);color:var(--dsw-alias-state-warning-primary,#d97706)}
       .fv-badge-add{background:color-mix(in srgb,var(--dsw-alias-state-success-primary,#10b981) 18%,transparent);color:var(--dsw-alias-state-success-primary,#10b981)}
-      .fv-modal-scrim{position:fixed;inset:0;z-index:70;display:grid;place-items:center;padding:16px;background:color-mix(in srgb,#000 45%,transparent);animation:fv-fade .15s ease-out;color-scheme:light dark}
+      .fv-modal-scrim{position:fixed;inset:0;z-index:70;display:grid;place-items:center;padding:16px;background:color-mix(in srgb,#000 45%,transparent);animation:fv-fade .15s ease-out}
       .fv-modal{width:min(94vw,560px);max-height:86vh;display:flex;flex-direction:column;border:1px solid var(--dsw-alias-border-l2);border-radius:14px;background:var(--dsw-alias-bg-layer-2,var(--dsw-alias-bg-base,#fff));box-shadow:var(--dsw-shadow-lv3);color:var(--dsw-alias-label-primary);overflow:hidden;font-family:var(--dsw-font-family)}
       .fv-modal-head{display:flex;align-items:center;justify-content:space-between;padding:14px 18px;border-bottom:1px solid var(--dsw-alias-border-l1)}
       .fv-modal-title{font:var(--dsw-font-m-16);font-weight:600;display:flex;align-items:center;gap:6px}
@@ -1458,22 +1458,28 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Trigger browser file download from a Blob using an ephemeral anchor tag.
+     * Trigger browser file download from a Blob or URL using an ephemeral anchor tag.
      */
-    function triggerDownload(blob, filename) {
-      if (typeof window === "undefined" || typeof document === "undefined") return false;
+    function triggerDownload(target, filename) {
+      const currentWin = typeof globalThis !== "undefined" && globalThis.window ? globalThis.window : (typeof window !== "undefined" ? window : null);
+      const currentDoc = typeof globalThis !== "undefined" && globalThis.document ? globalThis.document : (typeof document !== "undefined" ? document : null);
+      if (!currentWin || !currentDoc) return false;
       try {
-        const url = URL.createObjectURL(blob);
-        const anchor = document.createElement("a");
+        const isBlob = typeof Blob !== "undefined" && target instanceof Blob;
+        const url = isBlob ? (currentWin.URL?.createObjectURL?.(target) || URL.createObjectURL(target)) : String(target);
+        const anchor = currentDoc.createElement("a");
         anchor.href = url;
         anchor.download = filename || "download";
         anchor.style.display = "none";
-        document.body.appendChild(anchor);
+        currentDoc.body.appendChild(anchor);
         anchor.click();
-        document.body.removeChild(anchor);
-        setTimeout(() => {
-          try { URL.revokeObjectURL(url); } catch (_) {}
-        }, 1500);
+        currentDoc.body.removeChild(anchor);
+        if (isBlob) {
+          const timer = setTimeout(() => {
+            try { (currentWin.URL?.revokeObjectURL || URL.revokeObjectURL)(url); } catch (_) {}
+          }, 60000);
+          if (typeof timer?.unref === "function") timer.unref();
+        }
         return true;
       } catch (_) {
         return false;
@@ -1481,14 +1487,160 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Request raw bytes from host via RPC and trigger browser download.
+     * Whether this page runs inside the Desktop (Electron) shell.
+     *
+     * The Desktop host ships this same UI inside Electron, where `<a download>`
+     * has no download panel to report progress in: the shell saves to a default
+     * folder or opens its own dialog, and a 100 MB transfer gives the user no
+     * feedback while it runs. A real browser owns progress, pause, resume and
+     * the save location, so handing it the URL is strictly better there than
+     * buffering the bytes in the page.
+     *
+     * Electron identifies itself in the UA (and in `process.versions`). A wrong
+     * answer only changes which transfer strategy runs, never which files may
+     * be read, so the probe stays cheap and silent.
+     * @param {any} win - the window to inspect.
+     * @returns {boolean} true when the page is the Desktop shell.
      */
-    function performDownload(requestFn, root, path, name, onToast) {
-      if (!root || !path || typeof requestFn !== "function") {
+    function isDesktopShell(win) {
+      try {
+        if (/Electron\//i.test(String(win?.navigator?.userAgent ?? ""))) return true;
+        const versions = win?.process?.versions;
+        return typeof versions?.electron === "string";
+      } catch (_) {
+        return false;
+      }
+    }
+
+    /**
+     * Download one file, choosing the transfer that fits the host shell.
+     *
+     * Two strategies, because the two shells have opposite needs:
+     *   - a browser has a download manager that owns progress, pause, resume
+     *     and the save location, so the authenticated URL is handed straight
+     *     to it — a HEAD probe first turns "413" and "404" into an immediate
+     *     notice instead of a failed download entry;
+     *   - the Desktop shell has no such panel, so the bytes stream through
+     *     `fetch` with a real-time percentage, then reach the save flow as a
+     *     blob. That path keeps the page responsive and is the only one that
+     *     can show progress inside the drawer.
+     * Both fall back to the RPC `bytes` method when the streaming route is
+     * unavailable, so an older host or a blocked route still downloads.
+     * @param {(method: string, payload: object) => Promise<any>} requestFn - RPC caller.
+     * @param {string} root - root id the file belongs to.
+     * @param {string} path - path relative to that root.
+     * @param {string} [name] - display name to save under.
+     * @param {(message: string) => void} [onToast] - progress and result sink.
+     * @returns {Promise<boolean>} whether a download was started.
+     */
+    async function performDownload(requestFn, root, path, name, onToast) {
+      if (!root || !path) {
         if (onToast) onToast("未指定下载文件路径");
-        return Promise.resolve(false);
+        return false;
       }
       const filename = name || baseNameOf(path);
+      const currentWin = typeof globalThis !== "undefined" && globalThis.window ? globalThis.window : (typeof window !== "undefined" ? window : null);
+      const currentDoc = typeof globalThis !== "undefined" && globalThis.document ? globalThis.document : (typeof document !== "undefined" ? document : null);
+
+      if (currentWin && currentDoc && currentWin.location && currentWin.location.origin) {
+        const downloadUrl = `/api/file-viewer/download?root=${encodeURIComponent(root)}&path=${encodeURIComponent(path)}&filename=${encodeURIComponent(filename)}`;
+        const canFetch = typeof currentWin.fetch === "function";
+
+        // 浏览器：把鉴权后的 URL 直接交给原生下载管理器（进度、暂停、续传、保存位置都由它负责）
+        if (canFetch && !isDesktopShell(currentWin)) {
+          try {
+            const head = await currentWin.fetch(downloadUrl, { method: "HEAD", credentials: "same-origin" });
+            if (head.status === 413) {
+              if (onToast) onToast("文件超过下载限制（上限 100MB）");
+              return false;
+            }
+            if (!head.ok) throw new Error(`HTTP ${head.status}`);
+          } catch (_) {
+            // A failed probe is not a failed download: the browser still owns
+            // the request and reports its own outcome.
+          }
+          const handed = triggerDownload(downloadUrl, filename);
+          if (handed) {
+            if (onToast) onToast(`已交由浏览器下载 ${filename}`);
+            return true;
+          }
+        }
+
+        // 桌面端（或直链不可用）：流式读取并实时显示百分比进度
+        if (canFetch) {
+          try {
+            if (onToast) onToast(`正在准备下载 ${filename}...`);
+            const resp = await currentWin.fetch(downloadUrl, { method: "GET", credentials: "same-origin" });
+            if (!resp.ok) {
+              if (resp.status === 413) {
+                if (onToast) onToast("文件超过下载限制（上限 100MB）");
+                return false;
+              }
+              throw new Error(`HTTP ${resp.status}`);
+            }
+
+            const contentLength = Number(resp.headers?.get?.("content-length")) || 0;
+            const total = Number.isFinite(contentLength) && contentLength > 0 ? contentLength : 0;
+
+            let blob;
+            if (resp.body && typeof resp.body.getReader === "function") {
+              const reader = resp.body.getReader();
+              const chunks = [];
+              let loaded = 0;
+              let lastUpdate = 0;
+
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (value) {
+                  chunks.push(value);
+                  loaded += value.byteLength;
+                  const now = Date.now();
+                  if (now - lastUpdate > 100 || (total > 0 && loaded >= total)) {
+                    lastUpdate = now;
+                    const percent = total > 0 ? Math.min(100, Math.round((loaded / total) * 100)) : 0;
+                    const progressText = total > 0
+                      ? `正在下载 ${filename} (${percent}% - ${formatBytes(loaded)} / ${formatBytes(total)})...`
+                      : `正在下载 ${filename} (${formatBytes(loaded)})...`;
+                    if (onToast) onToast(progressText);
+                  }
+                }
+              }
+              const mime = resp.headers?.get?.("content-type") || "application/octet-stream";
+              blob = new Blob(chunks, { type: mime });
+            } else if (typeof resp.blob === "function") {
+              blob = await resp.blob();
+            } else {
+              blob = new Blob([await resp.arrayBuffer()]);
+            }
+
+            const ok = triggerDownload(blob, filename);
+            if (onToast) {
+              onToast(ok ? `✓ 下载完成 ${filename} (${formatBytes(blob.size)})` : "下载触发失败，请重试");
+            }
+            return ok;
+          } catch (err) {
+            if (err?.message?.includes("413") || err?.code === "too-large") {
+              if (onToast) onToast("文件超过下载限制（上限 100MB）");
+              return false;
+            }
+            // 流式通道异常时继续尝试直链与 RPC
+          }
+        }
+
+        // 无 fetch 环境：只能把 URL 交给宿主处理
+        const direct = triggerDownload(downloadUrl, filename);
+        if (direct) {
+          if (onToast) onToast(`已交由浏览器下载 ${filename}`);
+          return true;
+        }
+      }
+
+      if (typeof requestFn !== "function") {
+        if (onToast) onToast("未配置有效的下载通道");
+        return false;
+      }
+
       if (onToast) onToast(`正在准备下载 ${filename}...`);
       return requestFn("bytes", { root, path })
         .then((res) => {
@@ -1503,7 +1655,7 @@ window.__ModuleLoader__.load({
         })
         .catch((err) => {
           const msg = err?.code === "too-large"
-            ? "文件超过下载限制（上限 20MB）"
+            ? "文件超过下载限制（上限 100MB）"
             : `下载失败: ${err?.message || "网络异常"}`;
           if (onToast) onToast(msg);
           return false;
@@ -3548,7 +3700,7 @@ window.__ModuleLoader__.load({
       langOverrideKey, isKnownLanguageId, setLanguageCatalog, getLanguageCatalog: () => languageCatalog, LanguagePicker,
       MARKDOWN_LABELS, MARKDOWN_CODE_LABELS, READ_BLOCK_LABELS, JSON_TREE_LABELS, DIFF_BLOCK_LABELS, ErrorBoundary,
       openViewerForPath, wrapWorkspaceOpenPath, wrapConnectionRpc, wrapChangesOpenFetch, wrapSidebarRight, parseFileResource, setupGlobalFileClickInterceptor, extractClickedPath, normalizeClickedPath, looksLikeFilePath, isFileOpenControl, isFileMentionCode, renderRootOptions,
-      triggerDownload, performDownload, SvgIconDownload,
+      triggerDownload, performDownload, isDesktopShell, SvgIconDownload,
     };
     return module.exports;
   }

package/lib/core.js

@@ -7,9 +7,26 @@
  * @module dsh-file-viewer/core
  */
 
-/** Largest binary payload the RPC channel will base64-encode for the browser. */
+/**
+ * Largest binary payload the RPC viewer channel will base64-encode (20 MB).
+ *
+ * This budget belongs to the in-page preview path, which ships bytes as a
+ * base64 string inside a JSON envelope: a 20 MB file already costs ~27 MB of
+ * wire text plus an `atob` decode on the main thread. Raising it would make
+ * every preview of a large PDF or image block the browser, so downloads —
+ * which have their own streaming path — deliberately do not share it.
+ */
 export const MAX_BYTES = 20 * 1024 * 1024
 
+/**
+ * Largest file the download endpoint will stream (100 MB).
+ *
+ * Kept separate from {@link MAX_BYTES} on purpose: a download is consumed by
+ * the save flow rather than decoded into the page, so it can afford a budget
+ * the in-page preview path could never justify.
+ */
+export const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024
+
 /** Largest text file the viewer reads as text at all. */
 export const MAX_TEXT_BYTES = 8 * 1024 * 1024
 
@@ -545,6 +562,38 @@ export function mediaTypeOf(path) {
   return Object.hasOwn(MEDIA_TYPE_BY_EXTENSION, ext) ? MEDIA_TYPE_BY_EXTENSION[ext] : undefined
 }
 
+/**
+ * Build a `Content-Disposition` value that survives non-ASCII file names.
+ *
+ * HTTP header values are ByteStrings: every code unit must be ≤ 0xFF, so a raw
+ * Chinese or emoji name makes `Response` reject the whole header (and the
+ * download fails with a 500). RFC 6266/5987 solves this with two parameters:
+ * a plain `filename=` fallback restricted to ASCII, and `filename*=` carrying
+ * the real name as percent-encoded UTF-8. Browsers prefer `filename*` when it
+ * is present, so the fallback only has to stay legal, not pretty.
+ *
+ * The fallback drops anything outside printable ASCII, then collapses the
+ * result so a name made entirely of non-ASCII characters still yields a usable
+ * value instead of an empty one.
+ * @param {string} name - the file name to advertise.
+ * @returns {string} a header value safe for any byte-string header carrier.
+ */
+export function contentDispositionFor(name) {
+  const raw = typeof name === 'string' ? name : ''
+  // Strip CR/LF first: those would end the header rather than appear in it.
+  const withoutBreaks = raw.replace(/[\r\n]+/g, ' ')
+  // Printable ASCII minus the quote and backslash that would break the quoting.
+  const ascii = withoutBreaks.replace(/[^\x20-\x7E]/g, '').replace(/["\\]/g, '')
+  const trimmed = ascii.trim()
+  const fallback = trimmed === '' || trimmed === '.' || trimmed === '..' ? 'download' : trimmed
+  const encoded = encodeURIComponent(withoutBreaks)
+  // encodeURIComponent leaves ' ( ) * ! unescaped; RFC 5987 forbids none of
+  // them but a stray ' would be read as the charset/language separator, so it
+  // is escaped explicitly.
+  const extValue = encoded.replace(/'/g, '%27')
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${extValue}`
+}
+
 /**
  * Which viewer renders this path. The client switches on this one word, so the
  * host and the client can never disagree about a file's kind.

package/lib/index.js

@@ -23,11 +23,13 @@ import z from '@deepseek-ai/schemastery'
 import {
   LANGUAGE_CATALOG,
   MAX_BYTES,
+  MAX_DOWNLOAD_BYTES,
   MAX_PREVIEW_BYTES,
   MAX_TEXT_BYTES,
   TEXT_PROBE_BYTES,
   appendMention,
   baseNameOf,
+  contentDispositionFor,
   detectLanguageFromText,
   extensionOf,
   formatDocTextToMarkdown,
@@ -42,6 +44,7 @@ import {
   joinPath,
   kindOf,
   langOf,
+  mediaTypeOf,
   normalizeSafePaths,
   parseGitStatus,
   parsePatchToDiffs,
@@ -59,11 +62,13 @@ import {
 export {
   LANGUAGE_CATALOG,
   MAX_BYTES,
+  MAX_DOWNLOAD_BYTES,
   MAX_PREVIEW_BYTES,
   MAX_TEXT_BYTES,
   TEXT_PROBE_BYTES,
   appendMention,
   baseNameOf,
+  contentDispositionFor,
   detectLanguageFromText,
   extensionOf,
   formatDocTextToMarkdown,
@@ -79,6 +84,7 @@ export {
   joinPath,
   kindOf,
   langOf,
+  mediaTypeOf,
   normalizeSafePaths,
   parseGitStatus,
   parsePatchToDiffs,
@@ -101,6 +107,15 @@ export const inject = ['fs', 'connection', 'settings', 'workspaceRegistry', 'ses
 export const NS = 'file-viewer'
 export const RPC_CHANNEL = '/dsh-file-viewer'
 
+/**
+ * Exact Fetch route that streams one file to the browser's save flow.
+ *
+ * Lives below `/api` so the Connection carrier applies its Host/Origin fence
+ * and browser-cookie admission before this handler ever runs; only an owner
+ * Peer (the same principal the RPC channel serves) reaches it.
+ */
+export const DOWNLOAD_ROUTE = '/api/file-viewer/download'
+
 const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
 
 export function liveField(schema) {
@@ -222,7 +237,8 @@ export const Config = z.object({
   safePaths: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('安全访问路径（除工作区外的可访问路径列表）'),
   safeAccessPaths: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('安全访问路径（safePaths 别名）'),
   extraRoots: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('额外根目录（向后兼容 safePaths）'),
-  maxBytes: z.natural().default(MAX_BYTES),
+  maxBytes: z.natural().default(MAX_BYTES).description('在线预览（图片/PDF/表格等）单文件上限，默认 20 MB'),
+  maxDownloadBytes: z.natural().default(MAX_DOWNLOAD_BYTES).description('下载到本地单文件上限，默认 100 MB'),
   settingsFile: z.string().default('').description('安全访问路径本地持久化配置文件路径（留空则默认保存在 ~/.dsh/file-viewer/settings.json）'),
 })
 
@@ -1178,6 +1194,105 @@ export async function handleRpc(ctx, options, method, payload, signal) {
   }
 }
 
+/**
+ * Map one thrown value onto a status plus a body that is safe to echo.
+ *
+ * Two rules matter here and both are enforced by the existing RPC channel
+ * (`handleRpc`), so the streaming route must not be a weaker door:
+ *   - backend fs failures carry host codes (`FS_TOO_LARGE`, `FS_NOT_FOUND`,
+ *     …) and must land on the status the client already switches on, or the
+ *     "exceeds 100 MB" notice never fires;
+ *   - the body is an opaque reason, never `error.message`, because fs errors
+ *     embed absolute host paths (`EACCES: … 'D:/repo/secret/.env'`).
+ * @param {unknown} error - the thrown value.
+ * @returns {{status: number, reason: string}} status and a path-free reason.
+ */
+export function downloadFailure(error) {
+  if (error instanceof ViewerError) {
+    const viewerStatus = {
+      'not-found': 404,
+      'not-a-directory': 403,
+      'is-a-directory': 403,
+      'unknown-root': 404,
+      'no-roots': 404,
+      'outside-root': 403,
+      'access-denied': 403,
+      'too-large': 413,
+      unsupported: 415,
+    }
+    return { status: viewerStatus[error.code] ?? 400, reason: error.code }
+  }
+  const code = typeof error?.code === 'string' ? error.code : ''
+  const fsStatus = {
+    FS_NOT_FOUND: 404,
+    FS_NOT_DIRECTORY: 403,
+    FS_NOT_REGULAR_FILE: 403,
+    FS_PERMISSION_DENIED: 403,
+    FS_SANDBOX_DENIED: 403,
+    FS_TOO_LARGE: 413,
+    FS_ABORTED: 499,
+    FS_IO_ERROR: 500,
+  }
+  if (Object.hasOwn(fsStatus, code)) return { status: fsStatus[code], reason: code }
+  return { status: 500, reason: 'download-failed' }
+}
+
+/**
+ * Stream one file to the browser's save flow under the authenticated API fence.
+ *
+ * Files are read through `ctx.fs` with the caller's signal so a cancelled
+ * download stops the host read, and the byte budget comes from
+ * `maxDownloadBytes` rather than the much smaller in-page preview budget.
+ */
+export async function handleDownloadRequest(ctx, options, request) {
+  try {
+    const url = new URL(request.url, 'http://dsh.local')
+    const root = url.searchParams.get('root') || undefined
+    const path = url.searchParams.get('path') || ''
+    const customFilename = url.searchParams.get('filename') || ''
+
+    const { target, relative } = await resolveInRoot(ctx, options, { root, path }, request.signal)
+    const info = await ctx.fs.stat(target, request.signal)
+    if (info === undefined) {
+      return new Response('not-found', { status: 404 })
+    }
+    if (info.type === 'directory') {
+      return new Response('is-a-directory', { status: 403 })
+    }
+
+    const maxBytes = options().maxDownloadBytes ?? MAX_DOWNLOAD_BYTES
+    if (typeof info.size === 'number' && info.size > maxBytes) {
+      return new Response('too-large', { status: 413 })
+    }
+
+    const naming = relative === '' ? target.displayPath : relative
+    const filename = customFilename || baseNameOf(naming)
+    const mime = mediaTypeOf(naming) || 'application/octet-stream'
+
+    const headers = {
+      'Content-Type': mime,
+      'Content-Disposition': contentDispositionFor(filename),
+      'Cache-Control': 'private, no-store',
+      'X-Content-Type-Options': 'nosniff',
+    }
+
+    if (request.method === 'HEAD') {
+      if (info.size !== undefined) headers['Content-Length'] = String(info.size)
+      return new Response(null, { headers })
+    }
+
+    // `readBytes` enforces the same budget, so a backend that reports no size
+    // still cannot hand back more than the download limit.
+    const bytes = await ctx.fs.readBytes(target, request.signal, maxBytes)
+    headers['Content-Length'] = String(bytes.byteLength)
+    return new Response(bytes, { headers })
+  } catch (error) {
+    const { status, reason } = downloadFailure(error)
+    ctx.logger?.warn?.(`file-viewer: download failed with ${reason}`)
+    return new Response(reason, { status })
+  }
+}
+
 /**
  * Register the browser-facing channel.
  * @param {import('@deepseek-ai/cordis').Context} ctx - host context.
@@ -1227,6 +1342,7 @@ export function apply(ctx, config = {}) {
       safeAccessPaths: settings?.safeAccessPaths ?? [],
       extraRoots: settings?.extraRoots ?? [],
       maxBytes: settings?.maxBytes ?? MAX_BYTES,
+      maxDownloadBytes: settings?.maxDownloadBytes ?? MAX_DOWNLOAD_BYTES,
       _updateSafePaths: updateSafePaths,
       _settingsFile: settingsFile,
     }
@@ -1238,5 +1354,24 @@ export function apply(ctx, config = {}) {
       (method, payload, signal) => handleRpc(ctx, options, method, payload, signal),
       { authority: 'trusted-host' },
     )
+    /*
+     * The download route is an optimization, not a requirement: the RPC
+     * `bytes` method still downloads anything the streaming path cannot
+     * reach. Registering a duplicate path throws inside `connection.fetch`
+     * (its exact-route table rejects collisions), so a failure here must
+     * degrade to the RPC path instead of aborting the whole plugin apply.
+     */
+    try {
+      if (typeof connectionCtx.connection?.fetch?.register === 'function') {
+        connectionCtx.connection.fetch.register({
+          path: DOWNLOAD_ROUTE,
+          methods: ['GET', 'HEAD'],
+          requestBody: 'buffered',
+          fetch: (request) => handleDownloadRequest(ctx, options, request),
+        })
+      }
+    } catch (error) {
+      ctx.logger?.warn?.(`file-viewer: download route unavailable, falling back to RPC (${error?.message || error})`)
+    }
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weniatall/dsh-file-viewer",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Workspace file viewer for DeepSeek Harness: file tree, syntax-highlighted code with language detection and manual override, images, PDF, Excel and Word",
   "type": "module",
   "main": "lib/index.js",