dsh-plugin-workbench 0.0.3 → 0.0.5

package/src/client/FilePreview.tsx

@@ -4,17 +4,17 @@
  * a syntax-highlighted layer (Ctrl/Cmd+S saves). Tabs are drag-reorderable.
  * Opening/closing the first/last tab is animated.
  */
-import { useCallback, useEffect, useRef, useState } from 'react'
+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 { highlightCode } from './highlight'
+import { detectLanguage, highlightCode } from './highlight'
 import { FileIcon } from './fileIcons'
 import type { FilesKey } from './locales'
 import { activateFile, closeFile, collapsePreview, moveTab, toggleWrap, useTabsState } from './store'
 import type { FsReadResult } from './FileExplorer'
 
 interface TabData {
-  status: 'loading' | 'loaded' | 'binary' | 'too-large' | 'error'
+  status: 'loading' | 'loaded' | 'image' | 'binary' | 'too-large' | 'error'
   content?: string
   draft?: string
   dirty?: boolean
@@ -37,6 +37,39 @@ const PREVIEW_MIN = 240
 const CHAT_MIN = 240
 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'
+
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'bmp', 'ico', 'svg'])
+
+/**
+ * Same-origin URL serving the file's bytes when it is a previewable image;
+ * undefined otherwise. Image tabs never go through the text RPC read — the
+ * host route resolves the path through the sandboxed fs service itself.
+ */
+function imageSrcOf(path: string): string | undefined {
+  const idx = path.lastIndexOf('.')
+  if (idx < 0 || idx === path.length - 1) return undefined
+  const ext = path.slice(idx + 1).toLowerCase()
+  return IMAGE_EXTENSIONS.has(ext) ? `${RAW_PREFIX}/${encodeURIComponent(path)}` : undefined
+}
+
+/**
+ * Above this size the overlay editor (syntax-highlight layer + transparent
+ * textarea) falls back to a plain textarea: re-injecting and re-laying out
+ * hundreds of KB of wrapped text on every keystroke is what makes the page
+ * lag. The plain textarea keeps editing, wrapping and scrolling — it only
+ * loses the colors, which files this big rarely need anyway.
+ */
+const HIGHLIGHT_MAX_BYTES = 64 * 1024
+
+/**
+ * Languages always rendered as a plain textarea, never the overlay: the
+ * highlight layer costs a full extra layout pass (and with CJK text a
+ * fragile alignment surface) for prose formats where colors add little.
+ */
+const PLAIN_LANGUAGES = new Set(['markdown'])
+
 function basenameOf(path: string): string {
   const trimmed = path.replace(/[\\/]+$/, '')
   const idx = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'))
@@ -62,6 +95,19 @@ function previewDataOf(result: FsReadResult): TabData {
   return { status: 'loaded', content: result.content, draft: result.content, dirty: false, size: result.size }
 }
 
+/**
+ * Gutter text for an editor: one logical line number per source line, as a
+ * single pre-formatted block (VS Code shows logical numbers even when soft
+ * wrap makes a line occupy several visual rows).
+ */
+function lineNumbersOf(content: string): string {
+  const count = content.split('\n').length
+  if (count <= 1) return '1'
+  const parts = new Array<string>(count)
+  for (let i = 0; i < count; i += 1) parts[i] = String(i + 1)
+  return parts.join('\n')
+}
+
 export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
   const { tabs, active, theme, collapsed, wrap } = useTabsState()
 
@@ -73,42 +119,65 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
   const cacheRef = useRef<Map<string, TabData>>(new Map())
   const hasOpenedRef = useRef(false)
   const [, bump] = useState(0)
+  const [imageFailed, setImageFailed] = useState<string | undefined>(undefined)
 
   const previewRef = useRef<HTMLDivElement>(null)
   const handleRef = useRef<HTMLDivElement>(null)
   const highlightRef = useRef<HTMLPreElement>(null)
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+  const gutterRef = useRef<HTMLDivElement>(null)
 
   const refresh = useCallback(() => bump((v) => v + 1), [])
 
-  // Read newly opened tabs and drop cache entries for closed tabs.
+  // 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).
   useEffect(() => {
     const cache = cacheRef.current
     for (const [path] of cache) {
       if (!tabs.includes(path)) cache.delete(path)
     }
-    const controllers: AbortController[] = []
-    for (const path of tabs) {
-      if (cache.has(path)) continue
-      cache.set(path, { status: 'loading' })
-      const controller = new AbortController()
-      controllers.push(controller)
-      readFile(path, controller.signal)
-        .then((result) => {
-          if (!controller.signal.aborted) {
-            cache.set(path, previewDataOf(result))
-            refresh()
-          }
-        })
-        .catch((error) => {
-          if (!controller.signal.aborted) {
-            cache.set(path, { status: 'error', message: error instanceof Error ? error.message : String(error) })
-            refresh()
-          }
-        })
+    const target = active ?? tabs[0]
+    if (target === undefined || cache.has(target)) {
+      refresh()
+      return undefined
+    }
+    const controller = new AbortController()
+    // Image files skip the text RPC read entirely: the raw-bytes route serves
+    // them straight into an <img> tag, so there is nothing to load here.
+    if (imageSrcOf(target) !== undefined) {
+      cache.set(target, { status: 'image' })
+      refresh()
+      return () => controller.abort()
     }
+    cache.set(target, { status: 'loading' })
+    readFile(target, controller.signal)
+      .then((result) => {
+        if (!controller.signal.aborted) {
+          cache.set(target, previewDataOf(result))
+          // Large content: yield one frame so the browser paints the
+          // loading→loaded transition before the heavy text layout runs —
+          // the UI stays responsive instead of freezing in the same frame
+          // as the tab-open interaction.
+          if (result.size > HIGHLIGHT_MAX_BYTES) requestAnimationFrame(refresh)
+          else refresh()
+        }
+      })
+      .catch((error) => {
+        if (!controller.signal.aborted) {
+          cache.set(target, { status: 'error', message: error instanceof Error ? error.message : String(error) })
+          refresh()
+        }
+      })
     refresh()
-    return () => controllers.forEach((c) => c.abort())
-  }, [tabs, readFile, refresh])
+    return () => controller.abort()
+  }, [tabs, active, readFile, refresh])
+
+  // A failed <img> (deleted file, oversized, …) must not keep showing the
+  // broken-image placeholder when the user switches away and back.
+  useEffect(() => {
+    setImageFailed(undefined)
+  }, [active])
 
   // Animate the last tab closing without a mount/unmount bounce: keep the pane
   // mounted while `hasOpenedRef` is set, then drop it after the transition.
@@ -131,6 +200,41 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
 
   const isOpen = !collapsed && (tabs.length > 0 || closing || hasOpenedRef.current)
 
+  const activeData = active !== undefined ? cacheRef.current.get(active) : undefined
+  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))
+  // Rebuild the gutter text only when the draft changes (not on every bump
+  // from tab switches or focus re-renders).
+  const gutterNumbers = useMemo(
+    () => (activeData?.status === 'loaded' ? lineNumbersOf(activeData.draft ?? '') : ''),
+    [activeData?.status, activeData?.draft],
+  )
+
+  // Keep the highlight layer and the line-number gutter in lockstep with the
+  // textarea on every frame while the editor is open: some engines don't fire
+  // scroll events during selection auto-scroll, which would otherwise leave
+  // the visible layer and the numbers behind the selection (drag-select
+  // misalignment). All layers are `overflow: auto|hidden` with identical
+  // content geometry, so the assignment is a no-op whenever they align.
+  useEffect(() => {
+    const pre = highlightRef.current
+    const ta = textareaRef.current
+    const gutter = gutterRef.current
+    if (ta === null || gutter === null) return undefined
+    let raf = 0
+    const tick = () => {
+      if (pre !== null) {
+        pre.scrollTop = ta.scrollTop
+        pre.scrollLeft = ta.scrollLeft
+      }
+      gutter.scrollTop = ta.scrollTop
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [isOpen, active, activeData?.status, plain])
+
   // Publish the rendered preview width so the skin's fixed top/bottom trim can
   // shift past this pane (covering only the chat).
   useEffect(() => {
@@ -209,11 +313,13 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
 
   const onTextareaScroll = useCallback((e: React.UIEvent<HTMLTextAreaElement>) => {
     const pre = highlightRef.current
+    const gutter = gutterRef.current
     const ta = e.currentTarget
     if (pre !== null) {
       pre.scrollTop = ta.scrollTop
       pre.scrollLeft = ta.scrollLeft
     }
+    if (gutter !== null) gutter.scrollTop = ta.scrollTop
   }, [])
 
   const onTabDragStart = useCallback((e: ReactDragEvent<HTMLDivElement>, path: string) => {
@@ -236,8 +342,6 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
     setDragPath(undefined)
   }, [])
 
-  const activeData = active !== undefined ? cacheRef.current.get(active) : undefined
-
   if (!isOpen) return null
 
   const renderBody = () => {
@@ -245,14 +349,22 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
     switch (activeData.status) {
       case 'loading':
         return <div className={styles.previewHint}>{t('preview.loading')}</div>
-      case 'loaded': {
-        const highlighted = active !== undefined ? highlightCode(activeData.draft ?? '', active) : ''
+      case 'loaded':
         return (
-          <div className={styles.editor} data-wrap={wrap ? 'on' : 'off'}>
-            <pre ref={highlightRef} className={styles.editorHighlight} aria-hidden="true">
-              <code dangerouslySetInnerHTML={{ __html: highlighted }} />
-            </pre>
+          <div
+            className={`${styles.editor}${plain ? ` ${styles.editorPlain}` : ''}`}
+            data-wrap={wrap ? 'on' : 'off'}
+          >
+            <div ref={gutterRef} className={styles.gutter} aria-hidden="true">
+              <div className={styles.gutterNumbers}>{gutterNumbers}</div>
+            </div>
+            {!plain && active !== undefined && (
+              <pre ref={highlightRef} className={styles.editorHighlight} aria-hidden="true">
+                <code dangerouslySetInnerHTML={{ __html: highlightCode(activeData.draft ?? '', active) }} />
+              </pre>
+            )}
             <textarea
+              ref={textareaRef}
               className={styles.editorTextarea}
               value={activeData.draft ?? ''}
               onChange={(e) => onTextareaChange(e.target.value)}
@@ -260,11 +372,36 @@ export function FilePreview({ t, readFile, writeFile }: FilePreviewProps) {
               onKeyDown={onKeyDown}
               spellCheck={false}
               wrap={wrap ? 'soft' : 'off'}
-              title={t('action.saveHint')}
             />
+            {language !== undefined && tooBig && <div className={styles.editorHint}>{t('preview.highlightOff')}</div>}
             {saveError !== undefined && <div className={styles.saveError}>{saveError}</div>}
           </div>
         )
+      case 'image': {
+        const src = active !== undefined ? imageSrcOf(active) : undefined
+        const name = active !== undefined ? basenameOf(active) : ''
+        if (src === undefined) {
+          return <div className={styles.previewHint}>{t('preview.binary')}</div>
+        }
+        if (imageFailed === active) {
+          return (
+            <div className={styles.previewHint}>
+              <div>{t('preview.imageFailed')}</div>
+              <div className={styles.previewMeta}>{name}</div>
+            </div>
+          )
+        }
+        return (
+          <div className={styles.imageView}>
+            <img
+              className={styles.image}
+              src={src}
+              alt={name}
+              onError={() => setImageFailed(active)}
+            />
+            <div className={styles.previewMeta}>{name}</div>
+          </div>
+        )
       }
       case 'binary':
         return (

package/src/client/files.module.css

@@ -235,6 +235,54 @@
   padding: 2px 8px 2px 0;
 }
 
+/* ---- Right-click context menu (VS Code-style) ---- */
+/* The maid-atelier skin styles every [role='menu'] with its own palette —
+   `color` follows the PAGE theme there, while our background follows the
+   WORKBENCH theme. When the two disagree (page dark + workbench light or
+   vice versa) the skin's higher-specificity color would paint menu text in a
+   shade that matches our background, making it unreadable. Lock the menu's
+   own colors to the workbench tokens so text always contrasts its bg. */
+.contextMenu {
+  position: fixed;
+  z-index: 10000;
+  min-width: 180px;
+  padding: 4px;
+  box-sizing: border-box;
+  border: 1px solid var(--fe-border-strong);
+  border-radius: 6px;
+  background: var(--fe-bg) !important;
+  box-shadow: 0 6px 24px rgba(0, 0, 0, 0.28);
+  font-size: 13px;
+  color: var(--fe-fg) !important;
+  user-select: none;
+}
+
+.contextMenuItem {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 5px 10px;
+  border-radius: 4px;
+  cursor: pointer;
+  white-space: nowrap;
+  color: inherit;
+}
+
+.contextMenuItem:hover {
+  background: var(--fe-selection) !important;
+  color: var(--fe-fg) !important;
+}
+
+.contextMenuItemDanger {
+  color: #f48771 !important;
+}
+
+.contextMenuDivider {
+  height: 1px;
+  margin: 4px 6px;
+  background: var(--fe-border);
+}
+
 /* ---- Split preview + tabs ---- */
 .preview {
   flex: 0 0 55%;
@@ -420,13 +468,73 @@
   position: relative;
   height: 100%;
   min-height: 0;
+  /* Line-number gutter width; the textarea and highlight layers shift past it. */
+  --fe-gutter: 44px;
+  /* Keep layout/paint churn local to the editor: huge wrapped content must
+     not invalidate the whole page on every edit or scroll. */
+  contain: layout paint;
+}
+
+/* Line-number gutter: a fixed column on the left that scrolls in lockstep
+   with the editor text (scrollTop synced from the textarea every frame). */
+.gutter {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: var(--fe-gutter);
+  box-sizing: border-box;
+  overflow: hidden;
+  border-right: 1px solid var(--fe-border);
+  background: var(--fe-sidebar-bg);
+  color: var(--fe-faint);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  line-height: 1.5;
+  user-select: none;
+  pointer-events: none;
+}
+
+.gutterNumbers {
+  padding: 12px 8px;
+  white-space: pre;
+  text-align: right;
+}
+
+/* Plain (no-overlay) editor: the textarea itself renders the visible text —
+   used for files without syntax highlighting (e.g. .txt novels) and for
+   files too large to re-highlight per keystroke without lag. */
+.editorPlain .editorTextarea {
+  color: var(--fe-fg);
+}
+
+/* Large-file notice chip: syntax highlight was dropped to stay responsive. */
+.editorHint {
+  position: absolute;
+  left: calc(var(--fe-gutter) + 8px);
+  bottom: 8px;
+  padding: 4px 10px;
+  border-radius: 4px;
+  background: var(--fe-hover);
+  color: var(--fe-muted);
+  font-size: 11px;
+  pointer-events: none;
 }
 
 .editorHighlight {
   position: absolute;
-  inset: 0;
+  top: 0;
+  bottom: 0;
+  left: var(--fe-gutter);
+  right: 0;
   margin: 0;
   padding: 12px;
+  /* The textarea reserves one extra line at the bottom (its caret reserve),
+     so it can scroll ~1 line further than this layer. Match that range so
+     the two layers never desync at the bottom of a long file — otherwise
+     drag-selection near the end would highlight text one line ABOVE the
+     visible text. */
+  padding-bottom: calc(12px + 1.5em);
   /* auto (not hidden): the highlight layer gets the same scrollbar gutter as
      the textarea, so both content boxes have identical widths and wrap at the
      same points. Its scrollbars stack invisibly beneath the textarea's. */
@@ -450,7 +558,10 @@
 
 .editorTextarea {
   position: absolute;
-  inset: 0;
+  top: 0;
+  bottom: 0;
+  left: var(--fe-gutter);
+  right: 0;
   box-sizing: border-box;
   margin: 0;
   padding: 12px;
@@ -498,6 +609,31 @@
   line-height: 18px;
 }
 
+/* Image preview: raw bytes arrive from the plugin's same-origin route. The
+   viewer centers the picture and shrinks it to fit the pane, letting the
+   body scroll when the file is larger than the available space. */
+.imageView {
+  height: 100%;
+  min-height: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 12px;
+  overflow: auto;
+  background: var(--fe-bg);
+}
+
+.image {
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+  border-radius: 4px;
+  box-shadow: 0 0 0 1px var(--fe-border);
+}
+
 .previewMeta {
   color: var(--fe-faint);
   font-size: 11px;
@@ -573,8 +709,13 @@
   font-style: italic;
 }
 
+/* Strong emphasis is color-only on purpose: `font-weight: bold` widens
+   glyphs, so the highlight layer would wrap at different points than the
+   textarea beneath it — drag-selection would then highlight text that no
+   longer matches the visible lines. Italic above is metric-neutral. */
 .editorHighlight :global(.hljs-strong) {
-  font-weight: bold;
+  color: var(--fe-accent);
+  font-weight: inherit;
 }
 
 /* ---- Skin chrome fix ----

package/src/client/index.ts

@@ -23,12 +23,16 @@ 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 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 openPath = (path: string) => ctx.workspaces.openPath(path)
 
   ctx.slots.inject('explorer', () => ctx.slots.register({
     name: 'explorer',
     locale: NS,
-    inject: () => ({ listDir, openPath }),
+    inject: () => ({ listDir, openPath, createFile, createDir, renameFile, removePath }),
   }, FileExplorer))
 
   ctx.slots.inject('explorer.preview', () => ctx.slots.register({

package/src/client/locales.ts

@@ -14,11 +14,26 @@ export const zh = {
   'tab.close': '关闭标签页',
   'tab.collapse': '收起文件详情',
   'tab.expand': '弹出文件详情',
+  'menu.open': '打开预览',
+  'menu.newFile': '新建文件',
+  'menu.newFolder': '新建文件夹',
+  'menu.rename': '重命名',
+  'menu.delete': '删除',
+  'menu.copyPath': '复制路径',
+  'menu.refresh': '刷新',
+  'menu.openSystem': '在系统中打开',
+  'prompt.newFileName': '新文件名',
+  'prompt.newFolderName': '新文件夹名',
+  'prompt.renameTo': '重命名为',
+  'confirm.deleteFile': '确定删除文件「{name}」吗？',
+  'confirm.deleteDir': '确定删除文件夹「{name}」及其全部内容吗？',
   'preview.loading': '加载中…',
   'preview.binary': '二进制文件，无法预览',
+  'preview.imageFailed': '图片加载失败',
   'preview.tooLarge': '文件过大，仅支持预览不超过 {limit}',
   'preview.emptyDir': '空目录',
   'preview.error': '加载失败',
+  'preview.highlightOff': '大文件：已关闭语法高亮（仍可编辑）',
 } as const
 
 export type FilesKey = keyof typeof zh
@@ -35,9 +50,24 @@ export const en: Record<FilesKey, string> = {
   'tab.close': 'Close tab',
   'tab.collapse': 'Collapse file details',
   'tab.expand': 'Expand file details',
+  'menu.open': 'Open preview',
+  'menu.newFile': 'New File',
+  'menu.newFolder': 'New Folder',
+  'menu.rename': 'Rename',
+  'menu.delete': 'Delete',
+  'menu.copyPath': 'Copy Path',
+  'menu.refresh': 'Refresh',
+  'menu.openSystem': 'Open in System',
+  'prompt.newFileName': 'New file name',
+  'prompt.newFolderName': 'New folder name',
+  'prompt.renameTo': 'Rename to',
+  'confirm.deleteFile': 'Delete file "{name}"?',
+  'confirm.deleteDir': 'Delete folder "{name}" and all its contents?',
   'preview.loading': 'Loading…',
   'preview.binary': 'Binary file, cannot preview',
+  'preview.imageFailed': 'Failed to load image',
   'preview.tooLarge': 'File too large to preview (limit {limit})',
   'preview.emptyDir': 'Empty directory',
   'preview.error': 'Load failed',
+  'preview.highlightOff': 'Large file: syntax highlighting off (still editable)',
 }

package/src/client/store.ts

@@ -140,6 +140,31 @@ export function activateFile(path: string): void {
   updateCurrent((ws) => (ws.active === path || !ws.tabs.includes(path) ? ws : { ...ws, active: path }))
 }
 
+/** Point any open tab at a new path after a rename (the disk path changed). */
+export function retargetFile(oldPath: string, newPath: string): void {
+  updateCurrent((ws) => {
+    if (!ws.tabs.includes(oldPath)) return ws
+    const tabs = ws.tabs.map((t) => (t === oldPath ? newPath : t))
+    return { ...ws, tabs, active: ws.active === oldPath ? newPath : ws.active }
+  })
+}
+
+/** Close every open tab at or under a path (used after deleting it). */
+export function closeFilesUnder(path: string): void {
+  updateCurrent((ws) => {
+    const sep = path.includes('\\') ? '\\' : '/'
+    const prefix = path.endsWith('\\') || path.endsWith('/') ? path : path + sep
+    const kept = ws.tabs.filter((t) => t !== path && !t.startsWith(prefix))
+    if (kept.length === ws.tabs.length) return ws
+    let active = ws.active
+    if (active !== undefined && (active === path || active.startsWith(prefix))) {
+      const index = ws.tabs.indexOf(active)
+      active = kept[Math.min(index, kept.length - 1)]
+    }
+    return { ...ws, tabs: kept, active }
+  })
+}
+
 /** Move a tab before another tab (drag-to-reorder). */
 export function moveTab(dragged: string, target: string): void {
   updateCurrent((ws) => {

package/src/dsh.d.ts

@@ -55,8 +55,17 @@ declare module '@deepseek-ai/cordis' {
       stat(target: unknown, signal?: AbortSignal): Promise<{ version: unknown; type: 'file' | 'directory' | 'other'; size?: number } | undefined>
       listDir(target: unknown, signal?: AbortSignal): Promise<Array<{ name: string; type: 'file' | 'directory' | 'other'; target: unknown; version?: unknown; size?: number }>>
       readText(target: unknown, signal?: AbortSignal): Promise<string>
+      readBytes(target: unknown, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>
       writeText(target: unknown, content: string, version?: unknown, signal?: AbortSignal, options?: { mode?: string; workspaceRoot?: string }): Promise<void>
       processPath(target: unknown): string
     }
+    webServer: {
+      /** Register a named HTTP route (exact path or prefix). Returns the disposer. */
+      register(route: {
+        kind: 'exact' | 'prefix'
+        path: string
+        handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void | Promise<void>
+      }): () => void
+    }
   }
 }