dsh-plugin-workbench 0.0.5 → 0.0.6

package/src/client/FilePreview.tsx

@@ -1,13 +1,17 @@
 /**
  * Split file preview with VS Code-style tabs and a directly-editable editor.
  * Files open in tabs; the active tab is an always-editable textarea overlaid on
- * a syntax-highlighted layer (Ctrl/Cmd+S saves). Tabs are drag-reorderable.
- * Opening/closing the first/last tab is animated.
+ * a syntax-highlighted layer (Ctrl/Cmd+S saves). Markdown files open in a
+ * RENDERED preview by default, with a button to switch to the editable source
+ * view. Tabs are drag-reorderable. Open files are watched on disk: external
+ * changes auto-sync clean tabs and flag dirty ones (click the badge to reload,
+ * discarding unsaved edits). Opening/closing the first/last tab is animated.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { DragEvent as ReactDragEvent, KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent } from 'react'
 import styles from './files.module.css'
 import { detectLanguage, highlightCode } from './highlight'
+import { renderMarkdown } from './markdown'
 import { FileIcon } from './fileIcons'
 import type { FilesKey } from './locales'
 import { activateFile, closeFile, collapsePreview, moveTab, toggleWrap, useTabsState } from './store'
@@ -20,6 +24,10 @@ interface TabData {
   dirty?: boolean
   size?: number
   message?: string
+  /** Markdown tabs: 'rendered' shows the compiled preview, 'source' the editor. */
+  view?: 'rendered' | 'source'
+  /** The file changed on disk while this tab holds unsaved edits. */
+  diskChanged?: boolean
 }
 
 export interface FsWriteResult {
@@ -31,6 +39,8 @@ export interface FilePreviewProps {
   t: (key: FilesKey, params?: Record<string, unknown>) => string
   readFile: (path: string, signal?: AbortSignal) => Promise<FsReadResult>
   writeFile: (path: string, content: string, signal?: AbortSignal) => Promise<FsWriteResult>
+  /** Replace the host-side watch set (the open tab paths). Idempotent diff. */
+  watchFiles: (paths: string[]) => Promise<void>
 }
 
 const PREVIEW_MIN = 240
@@ -40,6 +50,15 @@ const PREVIEW_TOO_LARGE_LABEL = '512KB'
 /** Same-origin raw-bytes route registered by the host half (see src/index.ts). */
 const RAW_PREFIX = '/dsh-plugin-files/raw'
 
+/** Same-origin SSE endpoint pushed by the host half (see src/index.ts). */
+const EVENTS_ENDPOINT = '/dsh-plugin-files/events'
+
+/**
+ * Above this size an .md file opens in source view: compiling a multi-hundred
+ * KB document and laying out its DOM is what makes the pane lag.
+ */
+const MD_RENDER_MAX_BYTES = 256 * 1024
+
 const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'bmp', 'ico', 'svg'])
 
 /**
@@ -89,10 +108,28 @@ function clamp(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value))
 }
 
+/** Parent directory of a path ('C:/a/b.md' → 'C:/a'; '' when there is none). */
+function dirnameOf(path: string): string {
+  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return idx > 0 ? path.slice(0, idx) : ''
+}
+
 function previewDataOf(result: FsReadResult): TabData {
   if (result.truncated) return { status: 'too-large', size: result.size }
   if (result.binary) return { status: 'binary', size: result.size }
-  return { status: 'loaded', content: result.content, draft: result.content, dirty: false, size: result.size }
+  const data: TabData = {
+    status: 'loaded',
+    content: result.content,
+    draft: result.content,
+    dirty: false,
+    size: result.size,
+  }
+  // Markdown opens in the rendered preview by default (source view for files
+  // too large to render responsively).
+  if (detectLanguage(result.path) === 'markdown' && result.size <= MD_RENDER_MAX_BYTES) {
+    data.view = 'rendered'
+  }
+  return data
 }
 
 /**
@@ -108,7 +145,7 @@ function lineNumbersOf(content: string): string {
   return parts.join('\n')
 }
 
-export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
+export function FilePreview({ t, readFile, writeFile, watchFiles }: FilePreviewProps) {
   const { tabs, active, theme, collapsed, wrap } = useTabsState()
 
   const [previewWidth, setPreviewWidth] = useState<number | null>(null)
@@ -129,6 +166,96 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
 
   const refresh = useCallback(() => bump((v) => v + 1), [])
 
+  // Mirror of the current tab list for the SSE handler (avoids stale closures).
+  const tabsRef = useRef(tabs)
+  useEffect(() => {
+    tabsRef.current = tabs
+  }, [tabs])
+
+  /**
+   * Re-read one open file from disk (external edit sync, or the disk-changed
+   * badge click). A reload always takes disk content — the auto-sync path only
+   * runs on clean tabs, and the badge click is the user's explicit choice to
+   * drop unsaved edits.
+   */
+  const reloadFromDisk = useCallback(async (path: string) => {
+    const data = cacheRef.current.get(path)
+    if (data === undefined || data.status !== 'loaded') return
+    try {
+      const result = await readFile(path)
+      const next = previewDataOf(result)
+      // Keep the user's chosen view; a reload never flips rendered/source.
+      cacheRef.current.set(path, { ...next, view: data.view, diskChanged: false })
+    } catch (error) {
+      // File gone / unreadable: surface the failure instead of stale content.
+      cacheRef.current.set(path, {
+        ...data,
+        status: 'error',
+        message: error instanceof Error ? error.message : String(error),
+        diskChanged: false,
+      })
+    }
+    refresh()
+  }, [readFile, refresh])
+
+  /**
+   * Handle one disk-change event for an open path. Clean tabs auto-sync;
+   * dirty tabs keep their unsaved edits and show the reload badge instead.
+   */
+  const syncFromDisk = useCallback((path: string) => {
+    const data = cacheRef.current.get(path)
+    if (data === undefined || data.status === 'loading' || data.status === 'image') return
+    if (data.status === 'error') {
+      // Previously failed tab: retry the read (e.g. the file was re-created).
+      void reloadFromDisk(path)
+      return
+    }
+    if (data.dirty === true) {
+      if (data.diskChanged !== true) {
+        data.diskChanged = true
+        refresh()
+      }
+      return
+    }
+    void reloadFromDisk(path)
+  }, [reloadFromDisk, refresh])
+
+  // Disk watch: tell the host which paths to watch (debounced), and re-send on
+  // every SSE (re)connect so a dropped stream heals itself.
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      void watchFiles([...tabs]).catch(() => {
+        // Host side not ready yet — the next tab change or SSE open retries.
+      })
+    }, 400)
+    return () => clearTimeout(timer)
+  }, [tabs, watchFiles])
+
+  // Disk change events pushed by the host (fs.watch + SSE).
+  useEffect(() => {
+    const source = new EventSource(EVENTS_ENDPOINT)
+    source.onopen = () => {
+      void watchFiles([...tabsRef.current]).catch(() => {
+        // Ignore — the next onopen or tab change re-syncs.
+      })
+    }
+    const onChange = (event: MessageEvent<string>) => {
+      try {
+        const payload = JSON.parse(event.data) as { path?: unknown }
+        if (typeof payload.path === 'string' && tabsRef.current.includes(payload.path)) {
+          syncFromDisk(payload.path)
+        }
+      } catch {
+        // Malformed frame — ignore.
+      }
+    }
+    source.addEventListener('change', onChange)
+    return () => {
+      source.removeEventListener('change', onChange)
+      source.close()
+    }
+  }, [syncFromDisk, watchFiles])
+
   // Read the ACTIVE tab's content. Other tabs load lazily on first
   // activation, so switching to a workspace with many large files doesn't
   // re-read every tab at once (which used to freeze the switch).
@@ -204,6 +331,14 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
   const language = active !== undefined ? detectLanguage(active) : undefined
   const tooBig = (activeData?.size ?? 0) > HIGHLIGHT_MAX_BYTES
   const plain = language === undefined || tooBig || (language !== undefined && PLAIN_LANGUAGES.has(language))
+  const isMarkdown = language === 'markdown'
+  const mdRenderable = (activeData?.size ?? 0) <= MD_RENDER_MAX_BYTES
+  // Rebuild the compiled markdown only when the draft (or the view mode)
+  // changes — never on tab switches or focus re-renders.
+  const mdHtml = useMemo(() => {
+    if (activeData?.status !== 'loaded' || !isMarkdown || activeData.view !== 'rendered') return ''
+    return renderMarkdown(activeData.draft ?? '', dirnameOf(active ?? ''))
+  }, [activeData?.status, activeData?.draft, activeData?.view, isMarkdown, active])
   // Rebuild the gutter text only when the draft changes (not on every bump
   // from tab switches or focus re-renders).
   const gutterNumbers = useMemo(
@@ -233,7 +368,7 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
     }
     raf = requestAnimationFrame(tick)
     return () => cancelAnimationFrame(raf)
-  }, [isOpen, active, activeData?.status, plain])
+  }, [isOpen, active, activeData?.status, activeData?.view, plain])
 
   // Publish the rendered preview width so the skin's fixed top/bottom trim can
   // shift past this pane (covering only the chat).
@@ -304,6 +439,15 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
     refresh()
   }, [active, refresh])
 
+  /** Flip the active markdown tab between rendered preview and source editor. */
+  const toggleMdView = useCallback(() => {
+    if (active === undefined) return
+    const data = cacheRef.current.get(active)
+    if (data === undefined || data.status !== 'loaded') return
+    data.view = data.view === 'rendered' ? 'source' : 'rendered'
+    refresh()
+  }, [active, refresh])
+
   const onKeyDown = useCallback((e: ReactKeyboardEvent<HTMLTextAreaElement>) => {
     if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 's') {
       e.preventDefault()
@@ -350,6 +494,14 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
       case 'loading':
         return <div className={styles.previewHint}>{t('preview.loading')}</div>
       case 'loaded':
+        if (isMarkdown && activeData.view === 'rendered') {
+          return (
+            <div
+              className={styles.mdPreview}
+              dangerouslySetInnerHTML={{ __html: mdHtml }}
+            />
+          )
+        }
         return (
           <div
             className={`${styles.editor}${plain ? ` ${styles.editorPlain}` : ''}`}
@@ -373,7 +525,8 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
               spellCheck={false}
               wrap={wrap ? 'soft' : 'off'}
             />
-            {language !== undefined && tooBig && <div className={styles.editorHint}>{t('preview.highlightOff')}</div>}
+            {isMarkdown && !mdRenderable && <div className={styles.editorHint}>{t('preview.mdRenderOff')}</div>}
+            {language !== undefined && !isMarkdown && tooBig && <div className={styles.editorHint}>{t('preview.highlightOff')}</div>}
             {saveError !== undefined && <div className={styles.saveError}>{saveError}</div>}
           </div>
         )
@@ -459,6 +612,19 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
                     <span className={styles.tabIcon}><FileIcon name={basenameOf(path)} /></span>
                     <span className={styles.tabName}>{basenameOf(path)}</span>
                     {data?.dirty === true && <span className={styles.tabDot} />}
+                    {data?.diskChanged === true && (
+                      <button
+                        type="button"
+                        className={styles.tabDiskBadge}
+                        title={t('tab.diskChanged')}
+                        onClick={(e) => {
+                          e.stopPropagation()
+                          void reloadFromDisk(path)
+                        }}
+                      >
+                        {'⟳'}
+                      </button>
+                    )}
                     <button
                       type="button"
                       className={styles.tabClose}
@@ -474,6 +640,16 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
                 )
               })}
             </div>
+            {isMarkdown && activeData?.status === 'loaded' && mdRenderable && (
+              <button
+                type="button"
+                className={styles.tabAction}
+                title={activeData.view === 'rendered' ? t('action.mdSource') : t('action.mdRender')}
+                onClick={toggleMdView}
+              >
+                {activeData.view === 'rendered' ? '📝' : '👁'}
+              </button>
+            )}
             <button
               type="button"
               className={`${styles.tabAction}${wrap ? ` ${styles.tabActionActive}` : ''}`}

package/src/client/files.module.css

@@ -128,6 +128,12 @@
   padding: 4px;
 }
 
+/* Keyboard focus lands on the tree container (rows push focus here so
+   Ctrl+C / Ctrl+V work right after a click); no visible focus ring. */
+.treeArea:focus {
+  outline: none;
+}
+
 .row {
   display: flex;
   align-items: center;
@@ -153,6 +159,42 @@
   color: var(--fe-fg);
 }
 
+/* Cut items stay visible but ghosted until the paste lands (OS explorer look). */
+.rowCut {
+  opacity: 0.45;
+}
+
+/* A directory row that will receive a drag-drop move gets an accent outline. */
+.rowDropTarget {
+  box-shadow: inset 0 0 0 1.5px var(--fe-accent);
+  background: var(--fe-selection);
+}
+
+/* ---- Clipboard status bar (Copy / Cut + Paste) ---- */
+.clipboardBar {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 8px;
+  border-bottom: 1px solid var(--fe-border);
+  background: var(--fe-hover);
+  color: var(--fe-fg);
+  font-size: 12px;
+}
+
+.clipboardText {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.clipboardHint {
+  color: var(--fe-faint);
+}
+
 .chevron {
   flex: none;
   width: 12px;
@@ -277,6 +319,12 @@
   color: #f48771 !important;
 }
 
+.contextMenuItemDisabled {
+  opacity: 0.45;
+  cursor: default;
+  pointer-events: none;
+}
+
 .contextMenuDivider {
   height: 1px;
   margin: 4px 6px;
@@ -457,6 +505,31 @@
   opacity: 0.85;
 }
 
+/* Disk-changed badge: the file changed on disk while this tab holds unsaved
+   edits; click to reload and discard them. */
+.tabDiskBadge {
+  flex: none;
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: var(--fe-accent);
+  cursor: pointer;
+  font-size: 12px;
+  line-height: 1;
+  width: 16px;
+  height: 16px;
+  border-radius: 3px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+}
+
+.tabDiskBadge:hover {
+  background: var(--fe-hover);
+  color: var(--fe-fg);
+}
+
 .previewBody {
   flex: 1;
   min-height: 0;
@@ -639,6 +712,212 @@
   font-size: 11px;
 }
 
+/* ---- Markdown rendered preview ---- */
+.mdPreview {
+  box-sizing: border-box;
+  height: 100%;
+  overflow: auto;
+  padding: 16px 20px 48px;
+  color: var(--fe-fg);
+  font-size: 14px;
+  line-height: 1.7;
+  word-wrap: break-word;
+}
+
+.mdPreview > :first-child {
+  margin-top: 0;
+}
+
+.mdPreview > :last-child {
+  margin-bottom: 0;
+}
+
+.mdPreview h1,
+.mdPreview h2,
+.mdPreview h3,
+.mdPreview h4,
+.mdPreview h5,
+.mdPreview h6 {
+  margin: 1.2em 0 0.5em;
+  line-height: 1.3;
+  font-weight: 600;
+  color: var(--fe-fg);
+}
+
+.mdPreview h1 {
+  font-size: 1.7em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid var(--fe-border);
+}
+
+.mdPreview h2 {
+  font-size: 1.4em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid var(--fe-border);
+}
+
+.mdPreview h3 {
+  font-size: 1.2em;
+}
+
+.mdPreview h4,
+.mdPreview h5,
+.mdPreview h6 {
+  font-size: 1.05em;
+}
+
+.mdPreview p {
+  margin: 0.6em 0;
+}
+
+.mdPreview ul,
+.mdPreview ol {
+  margin: 0.6em 0;
+  padding-left: 1.6em;
+}
+
+.mdPreview li {
+  margin: 0.2em 0;
+}
+
+.mdPreview li > ul,
+.mdPreview li > ol {
+  margin: 0.2em 0;
+}
+
+.mdPreview a {
+  color: var(--fe-accent);
+  text-decoration: none;
+}
+
+.mdPreview a:hover {
+  text-decoration: underline;
+}
+
+.mdPreview blockquote {
+  margin: 0.8em 0;
+  padding: 0.3em 1em;
+  border-left: 3px solid var(--fe-border-strong);
+  color: var(--fe-muted);
+  background: var(--fe-sidebar-bg);
+}
+
+.mdPreview code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.92em;
+  background: var(--fe-hover);
+  padding: 0.15em 0.4em;
+  border-radius: 3px;
+}
+
+.mdPreview pre {
+  margin: 0.8em 0;
+  padding: 12px;
+  overflow: auto;
+  background: var(--fe-sidebar-bg);
+  border: 1px solid var(--fe-border);
+  border-radius: 4px;
+  line-height: 1.5;
+}
+
+.mdPreview pre code {
+  background: transparent;
+  padding: 0;
+  font-size: 13px;
+}
+
+.mdPreview table {
+  border-collapse: collapse;
+  margin: 0.8em 0;
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.mdPreview th,
+.mdPreview td {
+  border: 1px solid var(--fe-border-strong);
+  padding: 6px 12px;
+}
+
+.mdPreview th {
+  background: var(--fe-sidebar-bg);
+  font-weight: 600;
+}
+
+.mdPreview img {
+  max-width: 100%;
+  border-radius: 4px;
+}
+
+.mdPreview hr {
+  border: none;
+  border-top: 1px solid var(--fe-border-strong);
+  margin: 1.5em 0;
+}
+
+/* Fenced code blocks reuse the same token palette as the overlay editor. */
+.mdPreview :global(.hljs-keyword),
+.mdPreview :global(.hljs-selector-tag),
+.mdPreview :global(.hljs-literal) {
+  color: var(--fe-token-keyword);
+}
+
+.mdPreview :global(.hljs-string),
+.mdPreview :global(.hljs-regexp),
+.mdPreview :global(.hljs-addition) {
+  color: var(--fe-token-string);
+}
+
+.mdPreview :global(.hljs-comment),
+.mdPreview :global(.hljs-quote) {
+  color: var(--fe-token-comment);
+  font-style: italic;
+}
+
+.mdPreview :global(.hljs-number),
+.mdPreview :global(.hljs-symbol),
+.mdPreview :global(.hljs-bullet) {
+  color: var(--fe-token-number);
+}
+
+.mdPreview :global(.hljs-title),
+.mdPreview :global(.hljs-section),
+.mdPreview :global(.hljs-title.function_) {
+  color: var(--fe-token-function);
+}
+
+.mdPreview :global(.hljs-type),
+.mdPreview :global(.hljs-built_in),
+.mdPreview :global(.hljs-class .hljs-title) {
+  color: var(--fe-token-type);
+}
+
+.mdPreview :global(.hljs-attr),
+.mdPreview :global(.hljs-attribute),
+.mdPreview :global(.hljs-variable),
+.mdPreview :global(.hljs-template-variable),
+.mdPreview :global(.hljs-params) {
+  color: var(--fe-token-variable);
+}
+
+.mdPreview :global(.hljs-tag),
+.mdPreview :global(.hljs-name) {
+  color: var(--fe-token-tag);
+}
+
+.mdPreview :global(.hljs-meta) {
+  color: var(--fe-token-meta);
+}
+
+.mdPreview :global(.hljs-emphasis) {
+  font-style: italic;
+}
+
+.mdPreview :global(.hljs-strong) {
+  font-weight: 600;
+}
+
 .placeholder {
   flex: 1;
   display: flex;

package/src/client/highlight.ts

@@ -65,7 +65,7 @@ export function detectLanguage(path: string): string | undefined {
   return EXTENSION_TO_LANGUAGE[ext]
 }
 
-function escapeHtml(value: string): string {
+export function escapeHtml(value: string): string {
   return value
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -74,6 +74,11 @@ function escapeHtml(value: string): string {
     .replace(/'/g, '&#39;')
 }
 
+/** True when a language id names a registered highlight.js language. */
+export function canHighlight(language: string): boolean {
+  return language !== '' && hljs.getLanguage(language) !== undefined
+}
+
 /** Highlight code for a file; returns safe HTML (code is HTML-escaped). */
 export function highlightCode(code: string, path: string): string {
   const language = detectLanguage(path)
@@ -86,3 +91,15 @@ export function highlightCode(code: string, path: string): string {
   }
   return escapeHtml(code)
 }
+
+/** Highlight a fenced code block by its declared language; escaped plain text when unknown. */
+export function highlightFence(code: string, language: string): string {
+  if (canHighlight(language)) {
+    try {
+      return hljs.highlight(code, { language, ignoreIllegals: true }).value
+    } catch {
+      // fall through to escaped text
+    }
+  }
+  return escapeHtml(code)
+}

package/src/client/index.ts

@@ -23,27 +23,46 @@ export function apply(ctx: Context): void {
   const listDir = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'list', { path }, signal))
   const readFile = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'read', { path }, signal))
   const writeFile = (path: string, content: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'write', { path, content }, signal))
+  const watchFiles = (paths: string[]) => unwrap(ctx.connection.rpc.call(CHANNEL, 'watch', { paths }))
   const createFile = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'createFile', { path }, signal))
   const createDir = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'createDir', { path }, signal))
   const renameFile = (path: string, to: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'rename', { path, to }, signal))
   const removePath = (path: string, signal?: AbortSignal) => unwrap(ctx.connection.rpc.call(CHANNEL, 'delete', { path }, signal))
+  const copyPath = (from: string, to: string, overwrite: boolean, signal?: AbortSignal) =>
+    unwrap(ctx.connection.rpc.call(CHANNEL, 'copy', { from, to, overwrite }, signal))
+  const revealInExplorer = (path: string, kind: 'file' | 'dir', signal?: AbortSignal) =>
+    unwrap(ctx.connection.rpc.call(CHANNEL, 'reveal', { path, kind }, signal))
   const openPath = (path: string) => ctx.workspaces.openPath(path)
 
   ctx.slots.inject('explorer', () => ctx.slots.register({
     name: 'explorer',
     locale: NS,
-    inject: () => ({ listDir, openPath, createFile, createDir, renameFile, removePath }),
+    inject: () => ({ listDir, openPath, revealInExplorer, createFile, createDir, renameFile, removePath, copyPath }),
   }, FileExplorer))
 
   ctx.slots.inject('explorer.preview', () => ctx.slots.register({
     name: 'explorer.preview',
     locale: NS,
-    inject: () => ({ readFile, writeFile }),
+    inject: () => ({ readFile, writeFile, watchFiles }),
   }, FilePreview))
 }
 
-async function unwrap<T>(result: Promise<{ ok: true; value: T } | { ok: false; error: { message: string } }>): Promise<T> {
+interface RpcFailure {
+  ok: false
+  error: { code: string; message: string }
+}
+
+/** Error carrying the host's machine-readable `code` (e.g. 'exists' on copy collision). */
+export interface RpcError extends Error {
+  code?: string
+}
+
+async function unwrap<T>(result: Promise<{ ok: true; value: T } | RpcFailure>): Promise<T> {
   const resolved = await result
-  if (!resolved.ok) throw new Error(resolved.error.message)
+  if (!resolved.ok) {
+    const error = new Error(resolved.error.message) as RpcError
+    error.code = resolved.error.code
+    throw error
+  }
   return resolved.value
 }