dsh-zen-remote 2.2.5 → 2.2.7

package/src/client/effects/remote-drop.ts

@@ -0,0 +1,269 @@
+import type { ClientContext } from '../compat/types.ts'
+import { decideRemoteDrop, rewrapFiles } from '../../client-data/remote-drop.ts'
+import type { RemoteDropItemDescriptor } from '../../client-data/remote-drop.ts'
+import { CURRENT_SESSION_STORAGE_KEY, parseCurrentSessionStorage } from '../../client-data/current-session.ts'
+import { en, zh } from '../locales.ts'
+
+/**
+ * The remote-session drop guard (RD-2): a document-level CAPTURE-phase drop
+ * listener that re-shapes file drops landing in a remote session before the
+ * host's own (bubble-phase, F4) handler sees them.
+ *
+ * The desktop app's zero-copy fast path is the problem: a File dragged from
+ * the OS keeps its disk path, the host turns it into an `@/absolute/path`
+ * mention chip without uploading bytes, and in a remote session that path
+ * names a file on THIS machine — the server-side session can never read it.
+ * The bridge global (`__DSH_HOST_PATHS__`) is contextBridge-exposed and
+ * deep-frozen, so it cannot be wrapped; instead the drop event itself is
+ * re-shaped: each File is re-wrapped (path-stripped, RD-1) into a fresh
+ * DataTransfer and redispatched as a synthetic DragEvent. The host's own
+ * pipeline then classifies it as a browser drag — the byte-upload branch —
+ * which the T51 fetch-route interception relays to the server. Mask
+ * cleanup, busy rejection, directory detection and the addFiles branch all
+ * stay the host's own code; nothing downstream is reimplemented here.
+ *
+ * Gates (all three must pass, decided by RD-1's pure function): the event
+ * is trusted (our redispatch is untrusted — that alone makes the guard
+ * loop-free), the Electron bridge exists (phone / plain-browser hosts are
+ * already on the upload branch), and the current session (`dsh.sessions.
+ * current`, read fresh at event time) is a `zr~` virtual id. A missing
+ * signal counts as a local session — the conservative direction: the only
+ * misfire a stale signal can cause is uploading bytes for a local drop,
+ * never losing one.
+ *
+ * Degrades to not-installed when DragEvent / DataTransfer construction is
+ * unavailable — back to exactly today's behavior (RD-4's interface.md
+ * documents this). Diagnostic counters for the settings-page diagnostics
+ * block are exported via {@link remoteDropDiagnostics}.
+ */
+
+interface StorageLike {
+  getItem(key: string): string | null
+}
+
+export interface RemoteDropDiagnostics {
+  /** The listener is mounted and armed (capability check passed, effect
+   * not yet disposed). */
+  installed: boolean
+  /** Why the capability check declined to install; `undefined` while
+   * installed (and after a dispose, which keeps the counters readable). */
+  notInstalledReason: string | undefined
+  /** Drops this guard stopped from reaching the host (both the blocked and
+   * the redispatched kind). */
+  intercepted: number
+  /** Synthetic path-stripped drops actually dispatched. */
+  redispatched: number
+  /** Drops stopped because they carried a folder (toast shown, nothing
+   * dispatched). */
+  blockedDirectories: number
+  /** Drops judged not-ours and released untouched. */
+  passthrough: number
+  /** Redispatches aborted because a re-wrap or a DataTransfer add threw —
+   * the original event was released instead (宁坏勿丢). */
+  rewrapFailed: number
+}
+
+/** Module-level singleton: the bundle has one document, so one guard state.
+ * Re-mounting (a plugin row reload) resets it. */
+let diagnostics: RemoteDropDiagnostics = freshDiagnostics()
+
+function freshDiagnostics(): RemoteDropDiagnostics {
+  return { installed: false, notInstalledReason: undefined, intercepted: 0, redispatched: 0, blockedDirectories: 0, passthrough: 0, rewrapFailed: 0 }
+}
+
+/** A snapshot for the diagnostics carriers (settings page). Copying keeps
+ * callers from holding a live reference into a later mount's state. */
+export function remoteDropDiagnostics(): RemoteDropDiagnostics {
+  return { ...diagnostics }
+}
+
+/** The contextBridge global's existence only — never touched otherwise
+ * (it is deep-frozen and must stay unwrapped). */
+function hostPathsOf(): unknown {
+  return (globalThis as { __DSH_HOST_PATHS__?: unknown }).__DSH_HOST_PATHS__
+}
+
+/** The current-session signal, read AT EVENT TIME (the selection changes
+ * while the page is open; a mount-time snapshot would go stale). Any
+ * storage failure reads as "no signal" = local session = passthrough. */
+function readCurrentSessionId(): string | undefined {
+  let raw: string | null
+  try {
+    const storage = (globalThis as { localStorage?: StorageLike | null }).localStorage
+    raw = storage === null || storage === undefined ? null : storage.getItem(CURRENT_SESSION_STORAGE_KEY)
+  } catch {
+    return undefined
+  }
+  const report = parseCurrentSessionStorage(raw)
+  return report.kind === 'open' ? report.sessionId : undefined
+}
+
+/** Reduce the drop's items to RD-1's descriptors. `undefined` when the
+ * entry API is missing entirely — directories cannot be detected, and the
+ * host's own semantics treat that as "no directories". Directory entries
+ * surface as file-kind items (their bytes are unreadable), which is what
+ * the block-directories branch keys on. */
+function collectItems(transfer: DataTransfer): RemoteDropItemDescriptor[] | undefined {
+  const out: RemoteDropItemDescriptor[] = []
+  for (const item of Array.from(transfer.items)) {
+    if (item.kind !== 'file') continue
+    if (typeof item.webkitGetAsEntry !== 'function') return undefined
+    const entry = item.webkitGetAsEntry()
+    out.push({ kind: 'file', isDirectory: entry?.isDirectory === true })
+  }
+  return out
+}
+
+/** The toast copy in the page's language (the plugin's namespace carries
+ * both dictionaries; the framework `t` seat is not reachable from a
+ * non-React effect — same pick as the bridge note). */
+function toastText(language: string | undefined): string {
+  const key = 'remoteDropFolderBlocked' as const
+  return typeof language === 'string' && language.startsWith('zh') ? zh[key] : en[key]
+}
+
+/** Take the host's「拖拽文件到此处添加」drop overlay back down after this
+ * guard has stopped a drop outright. The overlay's own state machine
+ * (`dsh-client-ui-attachment` drop-events.ts) closes on the reset() inside
+ * its DOCUMENT-level bubble `drop` handler — which this guard's capture
+ * stopPropagation deliberately prevents from running — or on `dragend` at
+ * `window` level, a channel it reads without isTrust-checking. An OS-file
+ * drag never delivers a native dragend (the drag source is the OS, not a
+ * page element), so a branch that eats the drop must fire a synthetic one
+ * itself or the overlay stays up forever. Only the folder-block branch
+ * calls this: the redispatch branch's synthetic drop reaches the host's
+ * bubble handler, whose own reset brings the overlay down. */
+function dismissHostDropOverlay(): void {
+  try {
+    window.dispatchEvent(new Event('dragend'))
+  } catch {
+    // No window / Event in this host: the overlay is the only casualty.
+  }
+}
+
+export function mountRemoteDropGuard(ctx: ClientContext): void {
+  ctx.effect(() => {
+    // Fresh state per mount: a plugin reload re-runs apply() and must not
+    // inherit the previous mount's counters or installed flag.
+    diagnostics = freshDiagnostics()
+
+    // Capability self-check — anything missing means "not installed",
+    // back to today's behavior. Counted, not thrown: the diagnostics
+    // block explains why the guard is absent.
+    if (typeof DragEvent !== 'function') {
+      diagnostics.notInstalledReason = 'drag-event-unavailable'
+      return () => {}
+    }
+    try {
+      new DataTransfer()
+    } catch {
+      diagnostics.notInstalledReason = 'datatransfer-unavailable'
+      return () => {}
+    }
+    if (hostPathsOf() === undefined) {
+      // Phone / plain-browser hosts: the bridge is absent and the host is
+      // already on the byte-upload branch — nothing to fix here.
+      diagnostics.notInstalledReason = 'host-paths-unavailable'
+      return () => {}
+    }
+    diagnostics.installed = true
+
+    // --- toast (folder-blocked notice), inline styles per the CSS split ---
+    let toast: HTMLDivElement | undefined
+    let toastTimer: ReturnType<typeof setTimeout> | undefined
+    const removeToast = (): void => {
+      if (toastTimer !== undefined) clearTimeout(toastTimer)
+      toastTimer = undefined
+      toast?.remove()
+      toast = undefined
+    }
+    const showToast = (): void => {
+      // Restart the window on rapid re-drops rather than stacking toasts.
+      removeToast()
+      const el = document.createElement('div')
+      el.dataset.zenRemote = 'remote-drop-toast'
+      el.textContent = toastText(navigator.language)
+      el.style.cssText = [
+        'position:fixed', 'left:50%', 'transform:translateX(-50%)',
+        // Safe-area habit shared with the overlay effects: keep clear of the
+        // home indicator, degrade to a plain 32px offset where env() is 0.
+        'bottom:calc(env(safe-area-inset-bottom, 0px) + 32px)',
+        'z-index:2147483000',
+        'background:rgba(0,0,0,.82)', 'color:#fff',
+        'font:13px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif',
+        'padding:10px 16px', 'border-radius:10px', 'max-width:90vw', 'text-align:center',
+        // Purely informational: never intercepts the taps under it.
+        'pointer-events:none',
+      ].join(';')
+      document.body.appendChild(el)
+      toast = el
+      toastTimer = setTimeout(removeToast, 3000)
+    }
+
+    const onDrop = (event: DragEvent): void => {
+      // Self-reentry guard first: the redispatched event is untrusted, and
+      // this capture listener would otherwise see it again.
+      if (!event.isTrusted) return
+      const transfer = event.dataTransfer
+      if (transfer === null || !transfer.types.includes('Files')) return
+      // Not a file drag: the host's own Files-in-types gate ignores the
+      // drop anyway — not a candidate, not counted.
+      const decision = decideRemoteDrop({
+        hasHostPaths: hostPathsOf() !== undefined,
+        currentSessionId: readCurrentSessionId(),
+        trusted: event.isTrusted,
+        items: collectItems(transfer),
+      })
+      if (decision.action === 'passthrough') {
+        diagnostics.passthrough += 1
+        return
+      }
+      if (decision.action === 'block-directories') {
+        // A folder cannot be fixed by single-file upload: stop the whole
+        // drop, say so, nothing is dispatched.
+        event.preventDefault()
+        event.stopPropagation()
+        dismissHostDropOverlay()
+        diagnostics.intercepted += 1
+        diagnostics.blockedDirectories += 1
+        showToast()
+        return
+      }
+      // redispatch: build the ENTIRE payload before stopping the original
+      // event — any failure below releases the original untouched, so the
+      // host still receives today's (path-chip) behavior instead of
+      // nothing at all.
+      try {
+        const rewrapped = rewrapFiles(Array.from(transfer.files))
+        if (rewrapped.length === 0) {
+          diagnostics.passthrough += 1
+          return
+        }
+        const payload = new DataTransfer()
+        for (const file of rewrapped) payload.items.add(file)
+        event.preventDefault()
+        event.stopPropagation()
+        diagnostics.intercepted += 1
+        // The host's drop handler sits on document, bubble phase (F4): a
+        // bubbling synthetic drop on document reaches it. Its own handler
+        // does the preventDefault / mask reset / addFiles work; our capture
+        // listener skips this event via the isTrusted gate above.
+        document.dispatchEvent(new DragEvent('drop', { bubbles: true, cancelable: true, dataTransfer: payload }))
+        diagnostics.redispatched += 1
+      } catch {
+        // A re-wrap or a single items.add threw (0-byte / exotic File):
+        // count it and let the original event flow — 宁坏勿丢.
+        diagnostics.rewrapFailed += 1
+      }
+    }
+    document.addEventListener('drop', onDrop, true)
+
+    return () => {
+      document.removeEventListener('drop', onDrop, true)
+      removeToast()
+      // Keep the counters readable after a dispose (the settings page may
+      // still be open mid-reload); `installed` is the armed flag only.
+      diagnostics.installed = false
+    }
+  }, 'dsh-zen-remote: remote drop guard')
+}

package/src/client/index.tsx

@@ -37,10 +37,13 @@ import { RemoteStatusIcon } from './RemoteStatusIcon.tsx'
 import { RemoteComposerBanner } from './RemoteComposerBanner.tsx'
 import { registerRemoteStatusUi } from './remote-status-register.ts'
 import { mountCurrentSessionReporter } from './current-session-report.ts'
+import { mountRemoteDropGuard } from './effects/remote-drop.ts'
 import { mountRemoteGroupExpansionKeeper } from './remote-group-expansion.ts'
 import { installRemoteApiFetch } from './remote-fetch.ts'
 import { installRemoteSessionGuard } from './effects/remote-session.ts'
 import { installModelGroupSide } from './effects/model-group-side.ts'
+import { DeliverableDownload, DocumentDownload } from './RemoteFileDownload.tsx'
+import { createSaveRemoteFile } from './remote-file-save.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -135,6 +138,15 @@ export function apply(ctx: ClientContext): void {
   // 的桌面端 App 正是远程会话所在；只在探测出的子客户端角色下运行，主
   // 服务端的页面探测一次后就静默。
   mountCurrentSessionReporter(ctx)
+  // 远程会话拖拽附件（RD-2）：document 级 capture 阶段的 drop 拦截。桌面端
+  // 的同机零拷贝会把拖入的文件变成 `@本机绝对路径` chip，远程会话里服务端
+  // 读不到这个路径——守卫把远程会话的文件拖拽改写成无路径 File 的合成
+  // drop（宿主原生管道按浏览器拖拽走字节上传，再由 T51 的 fetch-route
+  // 拦截经中继转服务端）。判定在 client-data/remote-drop.ts（纯函数），
+  // 这里只做监听与重派发。同样必须在桌面门之前挂载：远程会话恰在桌面端
+  // 全宽使用；三门全不中（本地会话 / 手机端无 bridge / 非受信事件）时
+  // 零干预，主服务端的页面不受影响。
+  mountRemoteDropGuard(ctx)
   // T64 服务端分组展开状态的记忆与恢复：宿主在工作区列表 ready 时会把不在
   // 列表里的分组展开记录清掉（retainAccountKeys），而本地工作区先 ready、
   // 服务端分组后并入，zr~ 键每次加载都被清掉、分组回到折叠。与上报器共用
@@ -156,6 +168,41 @@ export function apply(ctx: ClientContext): void {
   // 桌面端子客户端的模型选单一样要分侧，桌面无手机外壳不影响它。
   installModelGroupSide(ctx)
 
+  // 2.2.6 远程会话产物下载：子客户端最常见的诉求是「把服务端工作区里刚产出的
+  // 文件拿到本机」。DSH 官方的产物卡片只有预览，打开类动作（present.open /
+  // open-in-app）作用于跑 DSH 的那台机器，远程会话里被样式表整组隐藏——
+  // 也就是说此前客户端根本没有把文件落到本机磁盘的入口。两个入口共用同一个
+  // 「读中继 + 浏览器下载」实现（RemoteFileDownload.tsx + remote-file-save.ts）：
+  // deliverable 卡片上的按钮从卡片自己的预览按钮 title 取绝对路径，
+  // 文档预览头的按钮直接拿 owner 给的 absolutePath；两者都只在虚拟会话渲染，
+  // 主服务端与本地会话逐像素 no-op。同样在桌面门之前注册——client 角色的
+  // 桌面端 App 正是远程会话所在。
+  const saveRemoteFileToLocal = createSaveRemoteFile(ctx)
+  ctx.slots.inject('deliverables.file.actions', () =>
+    ctx.slots.register(
+      {
+        name: 'deliverables.file.actions',
+        id: 'zr-download',
+        order: 40,
+        locale: NS,
+        inject: () => ({ saveFile: saveRemoteFileToLocal }),
+      },
+      DeliverableDownload,
+    ),
+  )
+  ctx.slots.inject('sidebar.right.tab.document.actions', () =>
+    ctx.slots.register(
+      {
+        name: 'sidebar.right.tab.document.actions',
+        id: 'zr-download',
+        order: 40,
+        locale: NS,
+        inject: () => ({ saveFile: saveRemoteFileToLocal }),
+      },
+      DocumentDownload,
+    ),
+  )
+
   // Desktop gate (DSH 0.1.7): the official Electron shell can be dragged
   // down to ~520px wide, where every width-based gate would flip the phone
   // shell on inside the desktop app. Inside that shell this plugin is a

package/src/client/locales.ts

@@ -253,6 +253,15 @@ export const zh = {
   'settings.client.diagRecentFailures': '最近的远程调用失败',
   'settings.client.diagCompatGroups': '指纹有差异的组：{groups}',
   'settings.client.diagCompatCalls': '最近的不兼容调用',
+  // --- RD-3 远程会话拖拽守卫的诊断行（浏览器端计数，渲染时现读） ---
+  'settings.client.diagRemoteDrop': '远程拖拽守卫',
+  'settings.client.diagRemoteDropOk': '已安装 · 拦截 {intercepted} · 重派发 {redispatched} · 文件夹 {blocked} · 放行 {passthrough} · 重包失败 {failed}',
+  'settings.client.diagRemoteDropOff': '未安装（{reason}）',
+  // --- RD-6 上传改道（fetch-route 拦截）的诊断行：读 remote-status 的 serviceProbe ---
+  'settings.client.diagUploadRedirect': '上传改道',
+  'settings.client.diagUploadRedirectOk': '已安装 · 上传已接管',
+  'settings.client.diagUploadRedirectRefused': '拒装：{reason}',
+  'settings.client.diagUploadRedirectPending': '服务注入未触发 · connection {connection} · fileUploads {fileUploads}',
   // --- PB-5 插件桥：主服务端同意小节 + 子客户端诊断小节 ---
   'settings.bridge.title': '插件桥',
   'settings.bridge.empty': '暂无插件登记插件桥',
@@ -294,6 +303,12 @@ export const zh = {
   'remoteGroupRevoked': '（令牌已吊销）',
   'remoteGroupUnpaired': '（已解除配对）',
   'remoteGroupMismatch': '（版本有差异）',
+  // --- 远程会话拖拽附件（RD-2）：文件夹被拦截时的短暂提示 ---
+  'remoteDropFolderBlocked': '远程会话暂不支持拖入文件夹',
+  // --- 2.2.6: 远程会话产物下载（deliverable 卡片 / 文档预览头） ---
+  'downloadToLocal': '下载到本机',
+  'downloadBusy': '下载中…',
+  'downloadFailed': '下载失败',
 } as const
 
 /** English dictionary, key-identical to the Chinese source of truth. */
@@ -543,6 +558,16 @@ export const en: Record<MobileNavKey, string> = {
   'settings.client.diagRecentFailures': 'Recent remote call failures',
   'settings.client.diagCompatGroups': 'Groups with fingerprint differences: {groups}',
   'settings.client.diagCompatCalls': 'Recent incompatible calls',
+  // --- RD-3: the remote drop guard's diagnostics line (browser-side
+  // counters, read at render time) ---
+  'settings.client.diagRemoteDrop': 'Remote drop guard',
+  'settings.client.diagRemoteDropOk': 'Installed · intercepted {intercepted} · redispatched {redispatched} · folders {blocked} · passthrough {passthrough} · rewrap failed {failed}',
+  'settings.client.diagRemoteDropOff': 'Not installed ({reason})',
+  // --- RD-6: the upload-redirect (fetch-route intercept) diagnostics row ---
+  'settings.client.diagUploadRedirect': 'Upload redirect',
+  'settings.client.diagUploadRedirectOk': 'Installed · upload wrapped',
+  'settings.client.diagUploadRedirectRefused': 'Refused: {reason}',
+  'settings.client.diagUploadRedirectPending': 'Service inject never fired · connection {connection} · fileUploads {fileUploads}',
   // --- PB-5 plugin bridge: host consent section + sub-client diagnostics ---
   'settings.bridge.title': 'Plugin bridge',
   'settings.bridge.empty': 'No plugin has registered a bridge yet',
@@ -583,6 +608,13 @@ export const en: Record<MobileNavKey, string> = {
   'remoteGroupRevoked': ' (token revoked)',
   'remoteGroupUnpaired': ' (unpaired)',
   'remoteGroupMismatch': ' (version mismatch)',
+  // --- RD-2: the short toast when a folder drop into a remote session is blocked ---
+  'remoteDropFolderBlocked': 'Folders cannot be dropped into a remote session yet',
+  // 2.2.6: remote-session artifact download (deliverable cards / document
+  // preview header).
+  'downloadToLocal': 'Download to this computer',
+  'downloadBusy': 'Downloading…',
+  'downloadFailed': 'Download failed',
 }
 
 /** Key domain of the `mobileNav` namespace (zh is the source of truth). */

package/src/client/remote-file-save.ts

@@ -0,0 +1,232 @@
+/**
+ * Saving one workspace file onto THIS machine (2.2.6, remote artifact
+ * download).
+ *
+ * DSH has no download surface at all: a produced file's card only PREVIEWS it
+ * through the document preview (`workspaceFiles/readBytes`), and the
+ * native-open controls (`present.open`, `changes.open`,
+ * `open-in-app`) act on the machine the DSH process runs on — which is why
+ * the remote-session stylesheet hides them. So on a paired desktop
+ * sub-client, a file the HOST produced in its workspace had no way to reach
+ * the client's disk. This module is the missing read+save half:
+ *
+ * - bytes come from the SAME relayed `workspaceFiles/readBytes` the preview
+ *   already uses (relay-access.ts registers the method; invoke-binary.ts
+ *   carries its `data` Uint8Array across the JSON channel),
+ * - they come in byte windows because the host's read window is capped
+ *   (`dsh-api-workspace-files` Config.maxBytes, 2 MiB by default): a full
+ *   read without a range is capped separately at `maxFileBytes` (32 MiB), so
+ *   ranged reads are the only shape that works for ANY produced file. A
+ *   `workspace-file/too-large` refusal carries the host's own limit in
+ *   `details.limit`, so the window adapts down instead of failing,
+ * - the assembled bytes become a Blob and a synthetic `<a download>` click,
+ *   the one save path a browser/webview gives a page without asking the
+ *   desktop shell for a native dialog.
+ *
+ * The pure half (`collectRemoteFile`, `downloadFileNameOf`) takes an injected
+ * reader and is driven directly by test/remote-file-save.test.cjs — no DOM,
+ * no DSH imports.
+ */
+import type { ClientContext, SessionId } from './compat/types.ts'
+
+/** The byte window one relayed read asks for. Matches the host default
+ * (`Config.maxBytes` 2 MiB) exactly: one round trip per window, and a host
+ * configured smaller self-corrects through the too-large branch below. */
+export const DOWNLOAD_CHUNK_BYTES = 2 * 1024 * 1024
+
+/** A hard ceiling on windows per file (4 GiB at the default size) — the
+ * guard against a reader that never advances (a host ignoring `range` and
+ * answering the same bytes forever) hanging the button in `busy`. */
+const MAX_DOWNLOAD_CHUNKS = 2048
+
+/** One byte window's answer, as the client Remote face delivers it. Only the
+ * fields this module reads are mirrored. */
+export type RemoteByteWindow =
+  | { ok: true; value: { data: Uint8Array; eof: boolean } }
+  | { ok: false; error: { code?: string; details?: { limit?: number } } }
+
+/** One ranged read bound to (session, path); the caller owns the closure. */
+export type RemoteByteRead = (range: { offset: number; length: number }) => Promise<RemoteByteWindow>
+
+/**
+ * The last path segment, as the browser download name. Slash- and
+ * backslash-separated paths both occur (the host may be Windows); an empty
+ * tail falls back to a fixed name so `download` is never blank.
+ * @param path - the file's absolute path on the host.
+ * @returns the name to save under.
+ */
+export function downloadFileNameOf(path: string): string {
+  const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  const name = (cut === -1 ? path : path.slice(cut + 1)).trim()
+  return name === '' ? 'download' : name
+}
+
+/** The three DOM reads {@link downloadPathFromCard} performs — structural so
+ * tests can pass fake nodes (a real Element satisfies it). */
+export interface DownloadCardNode {
+  closest(selector: string): DownloadCardNode | null
+  querySelector(selector: string): DownloadCardNode | null
+  getAttribute(name: string): string | null
+}
+
+/**
+ * The file path a produced-file card carries, read off the host's own
+ * rendered contract: the card root is `[data-presented-file]`, and its
+ * preview button's `title` is the resolved workspace path (RT
+ * dsh-client-ui-deliverables PresentedFileCard: `title:
+ * resolveWorkspacePath(cwd, file.path)`). The action button mounts inside
+ * that card, so `closest` picks THIS card, never a neighbouring one.
+ * @param button - the download action's own DOM node.
+ * @returns the path, or undefined when the card shape is not there (a future
+ * host): the caller then reports failure instead of guessing a path.
+ */
+export function downloadPathFromCard(button: DownloadCardNode | null): string | undefined {
+  const card = button?.closest('[data-presented-file]')
+  if (card === null || card === undefined) return undefined
+  // Prefer the DIRECT child: the card's preview overlay is the first child
+  // button, while this action (and open-in-app's control) live deeper in the
+  // actions cell — and this action carries a `title` of its own, so a broad
+  // `querySelector('button[title]')` could match ITSELF on a host whose card
+  // markup differs. `:scope` narrows the match to the card's own children.
+  let preview: DownloadCardNode | null = null
+  try {
+    preview = card.querySelector(':scope > button[title]')
+  } catch {
+    preview = null
+  }
+  preview ??= card.querySelector('button[title]')
+  const title = preview?.getAttribute('title')?.trim()
+  return title === undefined || title === '' ? undefined : title
+}
+
+/**
+ * Read one file window by window and return its complete bytes.
+ *
+ * The window starts at `chunkBytes` and adapts DOWN when the host refuses a
+ * window as too large (`workspace-file/too-large` + `details.limit`), so a
+ * host configured below the default still completes. The loop ends at the
+ * host's own `eof` flag, or on an empty window (never spin on a server that
+ * reports neither).
+ * @param read - one ranged read, already bound to the session and path.
+ * @param chunkBytes - the first window size; tests inject a small one.
+ * @returns the complete file bytes, in one buffer.
+ * @throws when a read is refused (the code rides the message) or the reader
+ * keeps advancing past {@link MAX_DOWNLOAD_CHUNKS} windows.
+ */
+export async function collectRemoteFile(
+  read: RemoteByteRead,
+  chunkBytes = DOWNLOAD_CHUNK_BYTES,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = []
+  let offset = 0
+  let size = Math.max(1, Math.floor(chunkBytes))
+  for (;;) {
+    if (chunks.length >= MAX_DOWNLOAD_CHUNKS) throw new Error('workspace-file/too-many-chunks')
+    const result = await read({ offset, length: size })
+    if (!result.ok) {
+      const limit = result.error.details?.limit
+      if (
+        result.error.code === 'workspace-file/too-large' &&
+        typeof limit === 'number' &&
+        Number.isSafeInteger(limit) &&
+        limit > 0 &&
+        limit < size
+      ) {
+        // The host's own window cap is below ours: take its number and retry
+        // the SAME offset — nothing was read.
+        size = limit
+        continue
+      }
+      throw new Error(result.error.code === undefined ? 'workspace-file/read-failed' : result.error.code)
+    }
+    const data = result.value.data
+    chunks.push(data)
+    offset += data.byteLength
+    if (result.value.eof || data.byteLength === 0) break
+  }
+  let total = 0
+  for (const chunk of chunks) total += chunk.byteLength
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const chunk of chunks) {
+    out.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return out
+}
+
+/** Save one file from a remote session to this machine. */
+export type SaveRemoteFile = (sessionId: SessionId, path: string) => Promise<void>
+
+/** The slice of the client `remote` service this module needs (the real one
+ * carries the whole workspaceFiles namespace; only readBytes is used). */
+interface RemoteFilesFace {
+  readBytes(
+    sessionId: SessionId,
+    path: string,
+    options: { range?: { offset: number; length: number } },
+    signal?: AbortSignal,
+  ): Promise<RemoteByteWindow>
+}
+
+/** Hand a finished byte array to the browser's download machinery. */
+function saveBytes(data: Uint8Array, fileName: string): void {
+  // `new Uint8Array(length)` always owns a plain ArrayBuffer; the cast only
+  // satisfies the BlobPart union in DOM typings that predate generic views.
+  const blob = new Blob([data as unknown as BlobPart], { type: 'application/octet-stream' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = downloadFileNameOf(fileName)
+  anchor.rel = 'noopener'
+  anchor.style.display = 'none'
+  document.body.append(anchor)
+  anchor.click()
+  anchor.remove()
+  setTimeout(() => {
+    URL.revokeObjectURL(url)
+  }, 60_000)
+}
+
+/**
+ * Bind the save capability the download buttons share to the client context.
+ *
+ * The `remote.workspaceFiles` service is looked up at CLICK time, not at
+ * registration time: a host without the service (an older DSH) must not
+ * break the plugin's apply, and the buttons only ever mount for a virtual
+ * session — where the service exists by construction.
+ * @param ctx - client root context.
+ * @returns the save function the injected `saveFile` prop carries.
+ */
+export function createSaveRemoteFile(ctx: ClientContext): SaveRemoteFile {
+  return async (sessionId, path) => {
+    // The namespace is BOTH a service of its own (`remote.workspaceFiles`) and
+    // reachable through the `remote` service's namespace proxy; ask for the
+    // exact service first and fall back to the proxy, so a composition that
+    // only provides one of the two still works.
+    const direct = ctx.get('remote.workspaceFiles') as RemoteFilesFace | undefined
+    const remote = ctx.get('remote') as { workspaceFiles?: RemoteFilesFace } | undefined
+    const files = direct ?? remote?.workspaceFiles
+    if (files === undefined) throw new Error('remote-unavailable')
+    let data: Uint8Array
+    try {
+      data = await collectRemoteFile((range) => files.readBytes(sessionId, path, { range }, undefined))
+    } catch (error) {
+      throw new Error(`read: ${describeError(error)}`, { cause: error })
+    }
+    try {
+      saveBytes(data, path)
+    } catch (error) {
+      throw new Error(`save: ${describeError(error)}`, { cause: error })
+    }
+  }
+}
+
+/** A short, user-visible reason: an error's message (the relay's failures
+ * carry their code as the message), else the thrown value's text. Kept short
+ * because it is rendered INSIDE the card's button. */
+function describeError(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error)
+  const trimmed = text.trim()
+  return trimmed.length > 40 ? `${trimmed.slice(0, 40)}…` : trimmed === '' ? 'unknown' : trimmed
+}