dsh-zen-remote 2.2.5 → 2.2.7

package/scripts/check-remote-drop.mjs

@@ -0,0 +1,114 @@
+// Behaviour check for the remote-drop decision core
+// (src/client-data/remote-drop.ts): the three-gate truth table, the
+// directory / no-directory / no-entry-API three-state rule,
+// block-directories precedence over redispatch, and the File re-wrap
+// keeping name/type/lastModified.
+//
+// Run: node scripts/check-remote-drop.mjs   (needs Node >= 23.6 type stripping)
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import {
+  decideRemoteDrop,
+  isRemoteSessionId,
+  rewrapFiles,
+} from '../src/client-data/remote-drop.ts'
+
+const REMOTE_ID = 'zr~0123abcd~session-1'
+const LOCAL_ID = 'session-6f2e9a10-1111-2222-3333-444455556666'
+const fileItem = { kind: 'file', isDirectory: false }
+
+// ---- 1. isRemoteSessionId ---------------------------------------------------
+assert.equal(isRemoteSessionId(REMOTE_ID), true, 'a virtual id is remote')
+assert.equal(isRemoteSessionId(LOCAL_ID), false, 'a plain session id is not remote')
+assert.equal(isRemoteSessionId(undefined), false, 'no signal is not remote')
+assert.equal(isRemoteSessionId(''), false, 'an empty id is not remote')
+assert.equal(isRemoteSessionId('zr~short'), false, 'the full zr~ skeleton is required, not the bare prefix')
+
+// ---- 2. the three-gate truth table -------------------------------------------
+// trusted x hasHostPaths x remote over one plain file item: exactly the
+// all-true row intervenes, every failing gate lands on passthrough with its
+// own reason (untrusted first, then no bridge, then local session).
+const truthTable = [
+  [{ trusted: true, hasHostPaths: true, remote: true }, 'redispatch', 'remote-files'],
+  [{ trusted: true, hasHostPaths: true, remote: false }, 'passthrough', 'not-remote-session'],
+  [{ trusted: true, hasHostPaths: false, remote: true }, 'passthrough', 'no-host-paths'],
+  [{ trusted: true, hasHostPaths: false, remote: false }, 'passthrough', 'no-host-paths'],
+  [{ trusted: false, hasHostPaths: true, remote: true }, 'passthrough', 'untrusted-event'],
+  [{ trusted: false, hasHostPaths: true, remote: false }, 'passthrough', 'untrusted-event'],
+  [{ trusted: false, hasHostPaths: false, remote: true }, 'passthrough', 'untrusted-event'],
+  [{ trusted: false, hasHostPaths: false, remote: false }, 'passthrough', 'untrusted-event'],
+]
+for (const [gates, action, reason] of truthTable) {
+  const decision = decideRemoteDrop({
+    trusted: gates.trusted,
+    hasHostPaths: gates.hasHostPaths,
+    currentSessionId: gates.remote ? REMOTE_ID : LOCAL_ID,
+    items: [fileItem],
+  })
+  assert.deepEqual(decision, { action, reason }, `gates ${JSON.stringify(gates)}`)
+}
+
+// ---- 3. directory / no-directory / no-entry-API -------------------------------
+// No entry API: redispatch with the host's own "no directories known" default.
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: undefined }),
+  { action: 'redispatch', reason: 'no-entry-api' },
+)
+// Files only: redispatch.
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [fileItem, fileItem] }),
+  { action: 'redispatch', reason: 'remote-files' },
+)
+// Any directory anywhere in the list: block, even mixed with plain files.
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [fileItem, { kind: 'file', isDirectory: true }] }),
+  { action: 'block-directories', reason: 'contains-directory' },
+)
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [{ kind: 'file', isDirectory: true }] }),
+  { action: 'block-directories', reason: 'contains-directory' },
+)
+// A file item whose entry cannot be read counts as NOT a directory.
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [{ kind: 'file', isDirectory: false }] }),
+  { action: 'redispatch', reason: 'remote-files' },
+)
+// String-only drags (no file items): the host's Files-in-types gate ignores
+// those anyway — passthrough, zero intervention.
+assert.deepEqual(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [{ kind: 'other', isDirectory: false }] }),
+  { action: 'passthrough', reason: 'no-files' },
+)
+
+// ---- 4. block-directories wins over redispatch ---------------------------------
+// Already covered mixed above; pin it once more against the empty-items edge:
+// a directory in an otherwise undecidable list still blocks.
+assert.equal(
+  decideRemoteDrop({ trusted: true, hasHostPaths: true, currentSessionId: REMOTE_ID, items: [{ kind: 'other', isDirectory: false }, { kind: 'file', isDirectory: true }] }).action,
+  'block-directories',
+)
+
+// ---- 5. rewrapFiles keeps name / type / lastModified ----------------------------
+const original = new File(['hello'], 'report.pdf', { type: 'application/pdf', lastModified: 1700000000000 })
+const [rewrapped] = rewrapFiles([original])
+assert.notEqual(rewrapped, original, 'the rewrap must produce a distinct File')
+assert.equal(rewrapped.name, 'report.pdf')
+assert.equal(rewrapped.type, 'application/pdf')
+assert.equal(rewrapped.lastModified, 1700000000000)
+assert.equal(rewrapped.size, original.size, 'the content must ride along')
+// Multiple files keep their order, and any iterable source works.
+const pair = rewrapFiles([original, new File([new Uint8Array([1, 2])], 'a.txt', { type: 'text/plain', lastModified: 1 })])
+assert.deepEqual(pair.map((f) => f.name), ['report.pdf', 'a.txt'])
+
+// ---- 6. the folder-block branch dismisses the host drop overlay ---------------
+// When a directory drop is stopped outright (no synthetic drop is redispatched),
+// the host's bubble drop handler never runs reset(); the guard must fire a
+// synthetic window `dragend` via dismissHostDropOverlay() so the overlay closes.
+{
+  const effects = readFileSync(new URL('../src/client/effects/remote-drop.ts', import.meta.url), 'utf8')
+  assert.ok(effects.includes('function dismissHostDropOverlay'), 'the guard defines dismissHostDropOverlay')
+  const calls = effects.match(/^\s*dismissHostDropOverlay\(\)\s*$/gm)?.length ?? 0
+  assert.equal(calls, 1, `the folder-block branch calls dismissHostDropOverlay() as a standalone statement (saw ${calls})`)
+}
+
+console.log('check-remote-drop: ok')

package/scripts/check-settings-form.mjs

@@ -457,8 +457,9 @@ test('the latest-wins gate drops tickets that are no longer newest (T15-fix 4)',
 test('deriveClientStatusView maps every probe state and tolerates garbage', () => {
   // T59: the view carries the device's own name ('' when the body had none).
   // PB-5: the bridge rows ([] — the body carried none) and the rerouting
-  // note (undefined) ride the same tolerant derivation.
-  const bare = { state: 'unpaired', serverUrl: '', serverName: '', deviceName: '', nextRetryAt: undefined, lastError: '', intercept: undefined, compat: undefined, pluginBridge: [], pluginRouteIntercept: undefined }
+  // note (undefined) ride the same tolerant derivation. RD-6: the
+  // upload-redirect probe (undefined — the body carried no serviceProbe).
+  const bare = { state: 'unpaired', serverUrl: '', serverName: '', deviceName: '', nextRetryAt: undefined, lastError: '', intercept: undefined, compat: undefined, pluginBridge: [], pluginRouteIntercept: undefined, uploadProbe: undefined }
   assert.deepEqual(deriveClientStatusView({ state: 'unpaired' }), bare)
   assert.deepEqual(deriveClientStatusView({ state: 'connected', serverUrl: 'http://192.168.1.10:3088' }), {
     ...bare,

package/scripts/check-upload-endpoint.mjs

@@ -89,6 +89,17 @@ try {
   assert.equal(ok.body.bytes, Buffer.byteLength(payload))
   assert.equal(await readFile(join(workspace, UPLOAD_DIR, 'notes.txt'), 'utf8'), payload)
 
+  // ---- the upload dir self-ignores in git ---------------------------------
+  // Files dropped into a session workspace would otherwise surface as
+  // untracked entries — and an agent's `git add -A` would commit the user's
+  // uploads. The directory ships a self-ignoring .gitignore created with the
+  // directory itself; a pre-existing (user-customized) one is never touched.
+  assert.equal(
+    await readFile(join(workspace, UPLOAD_DIR, '.gitignore'), 'utf8'),
+    '*\n!.gitignore\n',
+    'upload dir gets a self-ignoring .gitignore',
+  )
+
   // ---- same name twice does not clobber -----------------------------------
   const again = await post('?session=session-live&name=notes.txt', 'second')
   assert.equal(again.status, 201)
@@ -165,7 +176,7 @@ try {
 
   // ---- the workspace holds exactly what was uploaded, nothing partial ------
   assert.deepEqual((await readdir(join(workspace, UPLOAD_DIR))).sort(), [
-    'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
+    '.gitignore', 'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
   ])
 
   // ---- T17: the admission wall the apply() wiring passes in ----------------
@@ -205,8 +216,8 @@ try {
       assert.equal(body.error.code, status === 401 ? 'unauthorized' : 'forbidden')
     }
     assert.deepEqual(await readdir(join(workspace, UPLOAD_DIR)), [
-      'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
-    ], 'a refused admit writes nothing')
+      '.gitignore', 'blob.bin', 'evil.txt', 'notes-1.txt', 'notes.txt',
+    ], 'a refused admit writes nothing (the .gitignore predates it, created with the dir)')
     assert.equal(logged, 7, 'the admission wall short-circuits before the logger, like the 405/403')
 
     const allowed = await fetch(`${admitBases[2]}/_dsh/mobile-nav/upload?session=session-live&name=admitted.txt`, {

package/src/adapters/dsh-better-sidebar/index.ts

@@ -38,7 +38,7 @@ import { SIDEBAR_METHODS, sidebarMethodNameOf } from './methods.js'
  * modules — and pinned to the original by a test in
  * test/adapter-better-sidebar.test.cjs, which fails the pair apart when
  * either side moves. */
-const RELAY_UPLOAD_CAP_BYTES = 100 * 1024 * 1024
+const RELAY_UPLOAD_CAP_BYTES = 500 * 1024 * 1024
 
 /** better-sidebar's own JSON body bound (lib/index.js:863
  * `MAX_BODY_BYTES = 1 << 20`) — the adapter forwards at most what the

package/src/client/MobileAttachButton.tsx

@@ -4,7 +4,7 @@ import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots
 import { IconPaperclipOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SessionId } from './compat/types.ts'
 import { NS } from './locales.ts'
-import { draftWithMention, rememberThumbnail, uploadUrl } from './attach-upload.ts'
+import { appendDraftOf, rememberThumbnail, uploadUrl, writeMention } from './attach-upload.ts'
 import { useOwnAttachUi } from './host-attach.ts'
 
 /** Full props for the composer attachment seat. */
@@ -49,8 +49,11 @@ async function uploadFile(sessionId: SessionId, file: File): Promise<string> {
  * host without one (DSH ≤ 0.1.2) everything below loads exactly as before.
  *
  * Every picked file takes the SAME path: upload to the node half, then append
- * `@.dsh-uploads/name` to the draft through `inputActions.setDraft` (the
- * official write path — no DOM value poking). S7.1 removed the split that used
+ * `@.dsh-uploads/name` to the draft through the official write path — no DOM
+ * value poking: `inputActions.appendDraft` where the running DSH exposes it
+ * (0.2.1-rc.3+ editor runtime; keeps the user's text and inline references),
+ * else `inputActions.setDraft` with the whole next draft (attach-upload.ts
+ * `writeMention`). S7.1 removed the split that used
  * to send inlineable images straight into the session with `session.prompt`:
  * one behaviour for every attachment, and the user always presses send.
  * MobileAttachChips renders the preview row off those same draft tokens.
@@ -84,19 +87,21 @@ export function MobileAttachButton({ t, sessionId, useInput, inputActions }: Mob
 
     setBusy(true)
     setError(null)
-    // setDraft takes the WHOLE next draft, so each mention is appended to the
-    // value we last wrote — unless the ref shows the user has typed since, in
-    // which case theirs wins and we append to that instead. (Rebasing on the
-    // ref unconditionally would lose a mention whenever React had not yet
+    // appendDraft (DSH 0.2.1-rc.3+) appends after whatever the composer holds
+    // right now, so no rebasing is needed. The setDraft fallback takes the
+    // WHOLE next draft, so each mention is appended to the value we last
+    // wrote — unless the ref shows the user has typed since, in which case
+    // theirs wins and we append to that instead. (Rebasing on the ref
+    // unconditionally would lose a mention whenever React had not yet
     // re-rendered us between two files of the same pick.)
+    const appends = appendDraftOf(inputActions) !== undefined
     let written = liveDraft.current
     try {
       for (const file of files) {
         const relPath = await uploadFile(sessionId, file)
         // Local preview for the chip row; a no-op for non-images.
         rememberThumbnail(relPath, file)
-        written = draftWithMention(liveDraft.current === written ? written : liveDraft.current, relPath)
-        inputActions.setDraft(written)
+        written = writeMention(inputActions, (appends || liveDraft.current === written) ? written : liveDraft.current, relPath)
       }
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : String(cause))

package/src/client/MobileAttachChips.tsx

@@ -80,6 +80,10 @@ export function MobileAttachChips({ t, useInput, inputActions }: MobileAttachChi
               type="button"
               data-mobile-nav="attach-chip-remove"
               aria-label={t('attachRemove', { name })}
+              // Removal stays on setDraft even where the host has appendDraft
+              // (DSH 0.2.1-rc.3+): append can only add text, and the public
+              // inputActions face has no span-replace verb, so lifting one
+              // token out still means writing the whole next draft.
               onClick={() => inputActions.setDraft(draftWithoutMention(draft, relPath))}
             >
               <IconCloseFillRegular size={14} />

package/src/client/MobileHome.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import type { ReactNode, TouchEvent as ReactTouchEvent } from 'react'
 import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 import {
@@ -368,6 +368,23 @@ export function MobileHome({
     return () => window.removeEventListener(GO_HOME_EVENT, onGoHome)
   }, [actions])
 
+  // Mirror the current phone view onto the AppFrame element itself so CSS inside
+  // the main column (session header hide + fade strip gate) can key off a direct
+  // ancestor attribute instead of relying solely on cross-subtree body:has(...)
+  // invalidation on iOS WebKit (especially across installViewportHeal's display
+  // toggle on standalone PWA launch).
+  useLayoutEffect(() => {
+    const frame = document.querySelector<HTMLElement>('[data-mobile-nav="frame"]')
+      ?? document.querySelector('[data-shell-overlay]')?.parentElement
+      ?? null
+    if (!phone || frame === null) {
+      frame?.removeAttribute('data-mobile-view')
+      return
+    }
+    frame.setAttribute('data-mobile-view', view)
+    return () => frame.removeAttribute('data-mobile-view')
+  }, [phone, view])
+
   const enter = (start: () => void): void => {
     start()
     setSheet(null)
@@ -376,19 +393,69 @@ export function MobileHome({
   }
 
   // Opens the OFFICIAL settings modal (dsh-client-ui-settings-general's
-  // SettingsRoot) by clicking its real trigger button — its "open" state is
+  // SettingsRoot) by clicking its real trigger — its "open" state is
   // component-local React state with no public setter, same reasoning as
-  // MobileSessionHeader's Chat/Trajectory tab click. The trigger mounts
-  // inside the sidebar's `sidebar.settings` footer slot
-  // (`[class$="_settingsArea"]`, the sidebar shell's stable class suffix —
-  // see dsh-client-ui-sidebar's SidebarRoot), which is display:none on the
-  // phone breakpoint (home.css.ts): `.click()` still dispatches (bypasses
-  // hit-testing, S2.1 precedent) and flips `open`, but the resulting
-  // `aria-modal="true"` dialog would still paint nothing without the portal
-  // fix in styles/chips.css.ts (`:has([aria-modal="true"])` un-hides exactly
-  // the ancestor chain down to it, not the whole sidebar).
+  // MobileSessionHeader's Chat/Trajectory tab click. The trigger lives in the
+  // sidebar's `sidebar.settings` footer slot (`[class$="_settingsArea"]`, the
+  // sidebar shell's stable class suffix — see dsh-client-ui-sidebar's
+  // SidebarRoot), which is display:none on the phone breakpoint
+  // (home.css.ts): `.click()` still dispatches (bypasses hit-testing, S2.1
+  // precedent) and flips `open`.
+  //
+  // DSH 0.2.1-rc.2 moved the entry: that slot now holds only the ACCOUNT
+  // launcher (aria-haspopup="menu"), and Settings is an item inside its menu
+  // — the `button[aria-haspopup="dialog"]` this used to forward to is gone
+  // (and the resulting dialog is a body portal now, so the chips.css.ts
+  // ancestor un-hide below no longer has anything to reveal). Hence the
+  // menu fallback; both paths keep the label-free, structure-free
+  // "dispatch a click on the official control" approach.
   const openSettings = (): void => {
-    document.querySelector<HTMLButtonElement>('[class$="_settingsArea"] button[aria-haspopup="dialog"]')?.click()
+    const area = document.querySelector<HTMLElement>('[class$="_settingsArea"]')
+    // Older DSH: the settings modal's own trigger sits in the settings area.
+    const direct = area?.querySelector<HTMLButtonElement>('button[aria-haspopup="dialog"]')
+    if (direct) {
+      direct.click()
+      return
+    }
+    // DSH 0.2.1-rc.2: the sidebar footer's settings area now holds only the
+    // ACCOUNT launcher (aria-haspopup="menu", data-signed-out), and 设置 /
+    // Settings is an item inside its menu — the dialog trigger this used to
+    // forward to no longer exists there, so the bare
+    // querySelector()?.click() silently no-oped (real-phone report
+    // 2026-10-21: "手机端右上角设置点了没反应"). Open the menu, then click the
+    // settings item.
+    //
+    // Two constraints from review: (1) menus are body portals and a sibling
+    // menu (session actions, model picker) may already be mounted, so the
+    // item must come from the menu THIS click opened — snapshot the existing
+    // ones and pick the newly mounted menu; (2) the item is located without
+    // depending on its label, because the account menu's copy is localized:
+    // 设置 / Settings is the FIRST menuitem in both the signed-in and the
+    // signed-out variant (AccountMenu items: settings, contact, signin/out),
+    // so the first item is the locale-independent anchor, with the label as
+    // a refinement if that order ever changes.
+    const launcher = area?.querySelector<HTMLButtonElement>('button[aria-haspopup="menu"], button')
+    if (!launcher) return
+    const before = new Set<Element>(document.querySelectorAll('[role="menu"]'))
+    launcher.click()
+    const pick = (): boolean => {
+      const menu = [...document.querySelectorAll<HTMLElement>('[role="menu"]')].find((el) => !before.has(el))
+      if (!menu) return false
+      const items = [...menu.querySelectorAll<HTMLButtonElement>('button[role="menuitem"]')]
+      const item = items.find((el) => /设置|Settings/i.test(el.textContent || '')) ?? items[0]
+      if (!item) return false
+      item.click()
+      return true
+    }
+    // React commits the menu in the click's own task; observe for the mount
+    // (a deferred sibling launcher cannot leave a stale poll behind) and give
+    // up instead of leaking the observer if it never appears.
+    if (pick()) return
+    const observer = new MutationObserver(() => {
+      if (pick()) observer.disconnect()
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
+    setTimeout(() => observer.disconnect(), 1000)
   }
 
   if (!phone) return null

package/src/client/RemoteFileDownload.tsx

@@ -0,0 +1,173 @@
+/**
+ * The "save this file to THIS machine" action for a REMOTE session (2.2.6).
+ *
+ * DSH's produced-file surfaces only ever OPEN a file: the deliverable card's
+ * overlay previews it in the document panel, and open-in-app's split button
+ * hands the path to the machine the DSH process runs on. On a paired desktop
+ * sub-client both of those are the HOST's machine, which is why the
+ * remote-session stylesheet hides the open controls — leaving a produced
+ * Word/PDF/zip with no way to reach the client's disk at all. This action
+ * fills exactly that gap: it reads the file through the relayed
+ * `workspaceFiles/readBytes` channel (src/client/remote-file-save.ts) and
+ * hands the bytes to the browser's download machinery, so the file lands on
+ * the machine whose screen the user is looking at.
+ *
+ * Two surfaces, one button:
+ *
+ * - `deliverables.file.actions` — the file card of a closing turn. The slot
+ *   deliberately hands its entries only the open-route coordinates
+ *   (`actionUrl`), NOT the path; the card's own preview button carries the
+ *   resolved absolute path in its `title` attribute (RT
+ *   dsh-client-ui-deliverables PresentedFileCard: `title:
+ *   resolveWorkspacePath(cwd, file.path)`), and the entry mounts INSIDE that
+ *   card (`[data-presented-file]`), so the button reads the same host-rendered
+ *   contract the plugin's stylesheets already anchor on. A card without the
+ *   attribute (a future host) simply renders no path and the button reports
+ *   the failure instead of guessing.
+ * - `sidebar.right.tab.document.actions` — the document preview header, where
+ *   the owner hands `absolutePath` directly (RT
+ *   dsh-client-ui-sidebar-documentpreview TextPreview `fileOwner`), so the
+ *   same file can be saved without hunting for the card again.
+ *
+ * Both registrations are unconditional; both COMPONENTS return null for a
+ * local session (`isVirtual`), so a host-role deployment — and every local
+ * session on a client deployment — renders exactly nothing.
+ */
+import { useRef, useState } from 'react'
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionId } from './compat/types.ts'
+import { isVirtual } from '../virtual-id.js'
+import { NS } from './locales.ts'
+import { downloadPathFromCard } from './remote-file-save.ts'
+import type { SaveRemoteFile } from './remote-file-save.ts'
+
+/**
+ * Structural mirrors of the two host slot contracts. This package does not
+ * depend on dsh-client-ui-deliverables / dsh-client-ui-sidebar-documentpreview
+ * (the owners' type-only merges would normally provide these), so the mirror
+ * records ONLY what this action reads: both slots are session-scoped lists;
+ * the card carries the open-route coordinates, the document header carries
+ * the resolved absolute path.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'deliverables.file.actions': {
+      kind: 'list'
+      scope: 'session'
+      owner: {
+        actionUrl: string
+        available: boolean
+        pending: boolean
+        onAction: (action: string, application?: string) => unknown
+      }
+    }
+    'sidebar.right.tab.document.actions': {
+      kind: 'list'
+      scope: 'session'
+      owner: { absolutePath: string }
+    }
+  }
+}
+
+type DownloadPhase = 'idle' | 'busy' | 'error'
+
+/** Translate seat of this plugin's namespace. */
+type Translate = PropsLocale<typeof NS>['t']
+
+/** The button's own inputs: the framework session id, the bound save
+ * capability, the copy, and — only on the document header — the absolute
+ * path; the card surface resolves its path from the card DOM. */
+interface DownloadButtonProps {
+  sessionId: SessionId
+  t: Translate
+  saveFile: SaveRemoteFile
+  absolutePath?: string | undefined
+}
+
+/**
+ * The save control. One download at a time; the label carries the three
+ * states (idle / saving / failed) so a failure is visible on the card instead
+ * of a silent no-op.
+ * @param props - session, copy, save capability and (header only) the path.
+ * @returns the button.
+ */
+function DownloadButton({ sessionId, t, saveFile, absolutePath }: DownloadButtonProps) {
+  const [phase, setPhase] = useState<DownloadPhase>('idle')
+  const [failure, setFailure] = useState<string | undefined>(undefined)
+  const buttonRef = useRef<HTMLButtonElement | null>(null)
+  const onClick = async (): Promise<void> => {
+    if (phase === 'busy') return
+    const path = absolutePath ?? downloadPathFromCard(buttonRef.current)
+    setFailure(undefined)
+    if (path === undefined) {
+      setFailure('no-path')
+      setPhase('error')
+      return
+    }
+    setPhase('busy')
+    try {
+      await saveFile(sessionId, path)
+      setPhase('idle')
+    } catch (error) {
+      // The reason is rendered INSIDE the button (short) and logged for the
+      // console: without it a failed download on a client we cannot debug is
+      // a dead end.
+      const reason = (error instanceof Error ? error.message : String(error)).trim()
+      console.error('[dsh-zen-remote] remote download failed:', path, error)
+      setFailure(reason === '' ? 'unknown' : reason.slice(0, 22))
+      setPhase('error')
+    }
+  }
+  const label = phase === 'busy' ? t('downloadBusy') : phase === 'error' ? (failure === undefined ? t('downloadFailed') : `${t('downloadFailed')} (${failure})`) : t('downloadToLocal')
+  return (
+    <button
+      ref={buttonRef}
+      type="button"
+      className="zr-download-action"
+      data-phase={phase}
+      aria-label={t('downloadToLocal')}
+      title={failure === undefined ? t('downloadToLocal') : `${t('downloadToLocal')} — ${failure}`}
+      onClick={() => {
+        void onClick()
+      }}
+    >
+      {label}
+    </button>
+  )
+}
+
+/** Props the delivered-file card entry receives. */
+export interface DeliverableDownloadProps
+  extends PropsRuntime<'deliverables.file.actions'>, PropsLocale<typeof NS> {
+  /** Bound by this plugin's registration: the relayed read+save capability. */
+  saveFile: SaveRemoteFile
+}
+
+/**
+ * The deliverable card entry. Renders nothing on a local session.
+ * @param props - the card slot's owner props plus the injected save
+ * capability and copy.
+ * @returns the save button, or null.
+ */
+export function DeliverableDownload({ sessionId, t, saveFile }: DeliverableDownloadProps) {
+  if (!isVirtual(sessionId)) return null
+  return <DownloadButton sessionId={sessionId} t={t} saveFile={saveFile} />
+}
+
+/** Props the document-preview header entry receives. */
+export interface DocumentDownloadProps
+  extends PropsRuntime<'sidebar.right.tab.document.actions'>, PropsLocale<typeof NS> {
+  /** Bound by this plugin's registration: the relayed read+save capability. */
+  saveFile: SaveRemoteFile
+}
+
+/**
+ * The document preview header entry. Renders nothing on a local session.
+ * @param props - the document slot's owner props plus the injected save
+ * capability and copy.
+ * @returns the save button, or null.
+ */
+export function DocumentDownload({ sessionId, t, saveFile, absolutePath }: DocumentDownloadProps) {
+  if (!isVirtual(sessionId)) return null
+  return <DownloadButton sessionId={sessionId} t={t} saveFile={saveFile} absolutePath={absolutePath} />
+}

package/src/client/attach-upload.ts

@@ -63,6 +63,53 @@ export function draftWithMention(draft: string, relPath: string): string {
   return `${draft} @${relPath} `
 }
 
+/**
+ * The two draft writers the attachment flow can use. `setDraft` replaces the
+ * WHOLE draft with plain text (and, on DSH 0.2.1+, drops any inline reference
+ * chips the user had in it); `appendDraft` adds text after the current draft
+ * as new paragraphs and keeps its text and references. DSH 0.2.1-rc.3 grew
+ * `appendDraft` on the composer editor runtime; it is optional here because
+ * older hosts — and, as of rc.3, the public slot `inputActions` face itself —
+ * do not carry it, so it is feature-detected at runtime, never assumed.
+ */
+export interface DraftWriter {
+  setDraft(text: string): void
+  appendDraft?: (text: string) => void
+}
+
+/**
+ * The host's non-destructive append, when the running DSH exposes one.
+ * @param actions - the slot's `inputActions` (or any object carrying them).
+ * @returns a bound `appendDraft`, or undefined when the host has none.
+ */
+export function appendDraftOf(actions: object): ((text: string) => void) | undefined {
+  const append = (actions as { appendDraft?: unknown }).appendDraft
+  return typeof append === 'function' ? (append as (text: string) => void).bind(actions) : undefined
+}
+
+/**
+ * Write one `@path` mention into the composer.
+ *
+ * Prefers `appendDraft` (no whole-draft rewrite, so nothing the user typed or
+ * referenced meanwhile can be lost); falls back to `setDraft` with
+ * {@link draftWithMention} over `base` on a host without it.
+ * @param actions - the draft writers.
+ * @param base - the draft to rebase onto for the `setDraft` fallback.
+ * @param relPath - workspace-relative path returned by the upload route.
+ * @returns the draft text the fallback wrote, or `base` unchanged when the
+ *   host appended for us (the next render's `useInput` carries the result).
+ */
+export function writeMention(actions: DraftWriter, base: string, relPath: string): string {
+  const append = appendDraftOf(actions)
+  if (append !== undefined) {
+    append(`@${relPath} `)
+    return base
+  }
+  const next = draftWithMention(base, relPath)
+  actions.setDraft(next)
+  return next
+}
+
 /**
  * Remove one `@path` mention from the draft — what a chip's × does.
  *