dsh-vscode-mode 0.18.0 → 0.19.1

package/src/client/ui/EditorView.ts

@@ -9,8 +9,10 @@
  */
 import React from 'react'
 import { createPortal } from 'react-dom'
+import { createRoot } from 'react-dom/client'
 import { EditorPane, EditorSplit, PassiveEditor, GroupPathbar } from './EditorPane.js'
 import { FloatingEditor } from './FloatingEditor.js'
+import { LargeTextView } from './LargeTextView.js'
 import { FloatingWindow } from './FloatingWindow.js'
 import { createLayout, parseLayout, syncTabs, ownerOf, focusGroup, moveTab, returnGroup, GROUP_LIMIT, MAIN_GROUP } from '../state/editorLayout.js'
 import { createTabDrag, hitTarget } from '../tabDrag.js'
@@ -47,7 +49,7 @@ import {
 import { useFileWatch } from './useFileWatch.js'
 import { createPdfPanel } from '../pdf/pdfPanel.js'
 import { SvnDiffPanel } from './SvnDiffPanel.js'
-import { applyOfficial, registerThemes, themeNameOf } from '../monaco/theme.js'
+import { applyOfficial, editorFont, registerThemes, themeNameOf } from '../monaco/theme.js'
 import { createDiffRenderer } from '../monaco/diffRender.js'
 import { ST, callIdAttr, noopHunk, summarize } from '../state/records.js'
 import { diffRegions } from '../state/regions.js'
@@ -318,6 +320,11 @@ export function EditorView(props) {
   const aiStatusTimer = React.useRef(null)
   const [error, setError] = React.useState(null)
   const [loadError, setLoadError] = React.useState(null)
+  const [largeCandidate, setLargeCandidate] = React.useState(null)
+  const [pagedFile, setPagedFile] = React.useState(null)
+  const [pageChanged, setPageChanged] = React.useState(null)
+  const pageIdentity = JSON.stringify([scope, sessionId, active])
+  const paging = pagedFile === pageIdentity
   const [loadStage, setLoadStage] = React.useState({ progress: 0, message: '准备加载编辑器…' })
   const [openInput, setOpenInput] = React.useState(false)
   const [pathDraft, setPathDraft] = React.useState('')
@@ -1013,6 +1020,9 @@ export function EditorView(props) {
     const seq = ++loadSeqRef.current
     setReceiptLoad({ path, cwd, sessionId: sid, sequence: seq, status: 'loading' })
     setLoadError(null)
+    setLargeCandidate(null)
+    setPagedFile(null)
+    setPageChanged(null)
     /**
      * 记下磁盘版本基线；markRead=true 表示本次真的从磁盘读了内容
      * （已读版本台账随之失效，下一轮轮询按新版本重新比对）。
@@ -1064,6 +1074,7 @@ export function EditorView(props) {
         setLoadStage((prev) => ({ progress: Math.max(84, prev.progress), message: '文件已读取，准备创建编辑器…' }))
         setStatus('已加载')
       } else {
+        if (res?.code === 'file-too-large') setLargeCandidate(JSON.stringify([scope, sid, path]))
         const base = res?.error ? String(res.error) : '读取失败'
         dapTrace('read-failed', { path, error: base, resolvedPath: res?.resolvedPath, cwd })
         // 带出 host 解析后的真实路径：跳转失败时一眼看出是路径解析错还是目标不存在
@@ -1222,7 +1233,7 @@ export function EditorView(props) {
    * @author ddj 2026年09月15号
    * @param change 轮询判定出的外部变更
    */
-  const onDiskChange = (change) => {
+  function onDiskChange(change) {
     if (!change || !change.path) return
     // 文件树同步：目录缓存按该路径失效并强制重列（外部新增/删除/改名都能看到）
     const eventId = emitFileChanged(change.path, { scope, kind: change.kind === 'deleted' ? 'structure' : 'text' })
@@ -1242,6 +1253,14 @@ export function EditorView(props) {
       }).catch(() => {})
       return
     }
+    if (change.kind === 'modified' && (paging || pageChanged === pageIdentity) && change.path === activeRef.current) {
+      // Invalidates the old page cursor immediately; retain an identity-scoped notice until explicit reread.
+      loadContent(change.path, sessionId, true)
+      setPageChanged(pageIdentity)
+      setStatus('文件已变化，请重新读取')
+      emitRefresh({ scope, paths: [change.path], kind: 'text', eventId })
+      return
+    }
     if (change.kind === 'modified') {
       // 干净缓冲：强制从磁盘重读（跳过 model 复用），差异标记随之重算
       loadContent(change.path, sessionId, true)
@@ -1264,7 +1283,10 @@ export function EditorView(props) {
    * @param path 文件路径
    * @returns 比对结果；模型不可用/读失败 → null（按「需要重载」处理）
    */
-  const readDiskCompare = (path) => {
+  function readDiskCompare(path) {
+    // A read-only page has no full Monaco buffer to compare. Acknowledge the observed
+    // version as changed so polling advances its baseline instead of invalidating every reread.
+    if (path === activeRef.current && (paging || pageChanged === pageIdentity)) return Promise.resolve({ equal: false })
     const model = modelsRef.current?.get(path)
     if (!model || typeof model.getValue !== 'function') return Promise.resolve(null)
     return rpc('edrv.read', { sessionId, path }).then((res) => {
@@ -2370,9 +2392,7 @@ export function EditorView(props) {
       language: 'plaintext',
       theme: themeNameOf(),
       fontFamily: 'var(--ds-font-family-code, ui-monospace, monospace)',
-      // 16px/21px：与 md 预览渲染态同字号，切分页/切组时观感不再跳变（ddj 2026-10-16）
-      fontSize: 16,
-      lineHeight: 21,
+      ...editorFont(),
       minimap: { enabled: !side, scale: 1 },
       glyphMargin: true,
       lineDecorationsWidth: 16,
@@ -3764,7 +3784,8 @@ export function EditorView(props) {
     }
   }, [])
 
-  const openPath = () => {
+  /** @private @author ddj 2026年10月22号 @description Probe a typed path; let oversized files enter the existing read-only paging flow. @returns Probe completion. */
+  function openPath() {
     const p = (pathDraft || '').trim()
     if (!p) return
     // 图片/PDF 文件跳过文本读探测（二进制会被 host 拒绝），直接进 tab 由专用预览接管
@@ -3774,8 +3795,9 @@ export function EditorView(props) {
       return
     }
     setStatus('打开中…')
-    rpc('edrv.read', { sessionId, path: p }).then((res) => {
-      if (res && res.ok) {
+    return rpc('edrv.read', { sessionId, path: p }).then((res) => {
+      // Only the explicit size-limit response may bypass the probe; other failures must remain visible.
+      if (res && (res.ok || res.code === 'file-too-large')) {
         openFile(p, false)
         setOpenInput(false); setPathDraft(''); setStatus('已打开'); setError(null)
       } else { setStatus('打开失败'); setError(res?.error ? String(res.error) : '打开失败') }
@@ -3907,9 +3929,19 @@ export function EditorView(props) {
     host.addEventListener('contextmenu', onCtx, true)
     return () => { unsubscribeBp?.(); host.removeEventListener('contextmenu', onCtx) }
   }
+  /** @private @author ddj 2026年10月22号 @param args Read-only page request. @returns Current Host capability result. */
+  function loadTextPage(args) { return rpc('edrv.textPage', args) }
+  /** @private @author ddj 2026年10月22号 @description Never replace a dirty or saving document with partial text. */
+  function openTextPages() {
+    if (largeCandidate !== pageIdentity || dirtyRef.current[active] || savingRef.current.has(active)) return
+    flushSave()
+    if (dirtyRef.current[active] || savingRef.current.has(active)) return
+    setPageChanged(null)
+    setPagedFile(pageIdentity)
+  }
   /** @private @author ddj 2026年10月16号 @param host Passive body. @param path Canonical file. @param groupId Owning group id（find 快照按组隔离）. @returns View-only cleanup, models remain workbench-owned. */
   function mountPassive(host, path, groupId) {
-    let disposed = false, keeper = null, subscription = null, observer = null, unbindGutter = null
+    let disposed = false, keeper = null, subscription = null, observer = null, unbindGutter = null, pageRoot = null
     const focus = () => { const owner = ownerOf(benchRef.current, path); if (owner) selectGroup(owner.id, path) }
     host.addEventListener('pointerdown', focus)
     if (isPdfPath(path) && pdfNodes.current.has(path)) {
@@ -3923,7 +3955,27 @@ export function EditorView(props) {
     void request.then((result) => {
       if (disposed) return
       host.textContent = ''
-      if (!result?.ok) { host.textContent = result?.error || '文件加载失败'; return }
+      if (!result?.ok) {
+        host.textContent = result?.error || '文件加载失败'
+        if (result?.code === 'file-too-large' && !binary) {
+          const button = document.createElement('button')
+          button.textContent = '只读分段查看'
+          /** @author ddj 2026年10月22号 @param event Pointer event. @description Do not focus and unmount the passive group before click. */
+          button.onpointerdown = (event) => event.stopPropagation()
+          /** @author ddj 2026年10月22号 @description Keep partial text out of passive models, autosave and editing commands. */
+          button.onclick = () => {
+            if (disposed || dirtyRef.current[path] || savingRef.current.has(path)) return
+            flushSave()
+            if (dirtyRef.current[path] || savingRef.current.has(path)) return
+            host.textContent = ''
+            host.removeEventListener('pointerdown', focus)
+            pageRoot = createRoot(host)
+            pageRoot.render(React.createElement(LargeTextView, { sessionId, path, loadPage: loadTextPage }))
+          }
+          host.appendChild(button)
+        }
+        return
+      }
       if (binary) {
         const image = document.createElement(isPdfPath(path) ? 'div' : 'img')
         if (isPdfPath(path)) image.textContent = 'PDF · 点击此编辑组继续查看和编辑'
@@ -3936,7 +3988,7 @@ export function EditorView(props) {
       if (result.version) { revRef.current[path] = result.version; recordBaseline(scope, path, result.version) }
       const editor = window.monaco.editor.create(host, { model, automaticLayout: true, minimap: { enabled: false }, scrollBeyondLastLine: false, glyphMargin: true,
         // 与焦点编辑器（ensureEditor）同观感参数：字号/行高/顶部留白（side 形态 6，tab 形态 8）/装饰宽度，切分页行号位置不跳变（ddj 2026-10-16）
-        fontFamily: 'var(--ds-font-family-code, ui-monospace, monospace)', fontSize: 16, lineHeight: 21,
+        fontFamily: 'var(--ds-font-family-code, ui-monospace, monospace)', ...editorFont(),
         lineDecorationsWidth: 16, padding: { top: layoutRef.current === 'side' ? 6 : 8 } })
       const unbindGutter = bindBpGutter(editor, host, path)
       keeper = createViewKeeper(editor)
@@ -3948,7 +4000,7 @@ export function EditorView(props) {
       observer = new ResizeObserver(() => editor.layout())
       observer.observe(host)
     }).catch((failure) => { if (!disposed) host.textContent = '文件加载失败：' + String(failure) })
-    return () => { disposed = true; host.removeEventListener('pointerdown', focus); unbindGutter?.(); observer?.disconnect(); subscription?.dispose(); keeper?.dispose(); paneEditors.current.delete(path) }
+    return () => { disposed = true; pageRoot?.unmount(); host.removeEventListener('pointerdown', focus); unbindGutter?.(); observer?.disconnect(); subscription?.dispose(); keeper?.dispose(); paneEditors.current.delete(path) }
   }
   const passiveOps = React.useRef(mountPassive)
   passiveOps.current = mountPassive
@@ -3976,7 +4028,7 @@ export function EditorView(props) {
     return React.createElement(EditorPane, { key: id, group, focused, dirty: dirtyMap, suppressActive: hideDiskActive, tabsRef: chrome ? tabsHostRef : undefined, extras: chrome ? planTabExtras : undefined, tools: chrome ? rowTools : undefined, onSelect: selectGroup, onClose: closeTab, onMenu: paneMenu, onDrag: dragTab, consumeClick: consumeDrag },
       focused ? React.createElement('div', { className: 'edrv-full-slot', ref: mountFull }) : React.createElement(React.Fragment, null,
         React.createElement(GroupPathbar, { path: group.active, onFocus: () => selectGroup(id) }),
-        React.createElement(PassiveEditor, { key: String(scope) + ':' + group.active, path: group.active, groupId: id, mount: passiveMount })))
+        React.createElement(PassiveEditor, { key: JSON.stringify([scope, sessionId, group.active]), path: group.active, groupId: id, mount: passiveMount })))
   }
   /** @private @author ddj 2026年10月14号 @param node Layout subtree. @returns Recursive resizable panes. */
   function renderTree(node) {
@@ -4176,6 +4228,12 @@ export function EditorView(props) {
       : React.createElement('pre', { className: 'edrv-mdview-pre' }, text)
     body = React.createElement('div', { className: 'edrv-mdview', ref: planHostRef, 'data-plan-address': activePlan.address },
       React.createElement('div', { className: 'edrv-mdview-stage' }, React.createElement('div', { className: 'edrv-mdview-doc' }, render)))
+  } else if (pageChanged === pageIdentity && largeCandidate === pageIdentity) {
+    body = React.createElement('div', { className: 'edrv-empty', role: 'status' },
+      React.createElement('div', null, '文件已变化，请重新读取'),
+      React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', onClick: openTextPages }, '重新读取首段'))
+  } else if (paging) {
+    body = React.createElement(LargeTextView, { key: pageIdentity, sessionId, path: active, loadPage: loadTextPage })
   } else if (!monaco && !monacoErr) {
     body = loadingBody(loadStage.message, loadStage.progress)
   } else if (monacoErr) {
@@ -4200,13 +4258,13 @@ export function EditorView(props) {
         loadContent(active, sessionId)
       } }, '重试'))
   } else if (content === null && loadError) {
-    body = loadingBody('文件加载失败：' + loadError, 0, () => {
+    body = React.createElement(React.Fragment, null, loadingBody('文件加载失败：' + loadError, 0, () => {
       setLoadError(null)
       setContent(null)
       setContentPath(null)
       setLoadStage({ progress: 10, message: '重新读取文件…' })
       loadContent(active, sessionId)
-    })
+    }), largeCandidate === pageIdentity && React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', onClick: openTextPages }, '只读分段查看'))
   } else if (isImageActive && imageSrc) {
     body = imagePanel()
   } else if (isImageActive) {

package/src/client/ui/LargeTextView.ts

@@ -0,0 +1,94 @@
+import React from 'react'
+import * as Primitives from '@deepseek-ai/dsh-client-ui-primitives'
+import { createTextPager } from '../textPages.js'
+import type { TextPageLoader, TextPagerState } from '../textPages.js'
+
+export interface LargeTextViewProps {
+  sessionId: string
+  path: string
+  loadPage: TextPageLoader
+}
+const Button = (Primitives as unknown as { Button: React.ComponentType<{
+  children?: React.ReactNode; disabled?: boolean; onClick?: () => void
+}> }).Button
+
+/**
+ * Read-only paged text surface: never creates a Monaco model or exposes a save action.
+ * @public @author ddj 2026年10月22号
+ * @param props Exact session/file identity and authorized page loader.
+ * @returns Bounded selectable text with explicit continuation and status.
+ */
+export function LargeTextView(props: LargeTextViewProps): React.ReactElement {
+  const [snapshot, setSnapshot] = React.useState<TextPagerState | null>(null)
+  const [identity, setIdentity] = React.useState('')
+  const pagerRef = React.useRef<ReturnType<typeof createTextPager> | null>(null)
+  const loaderRef = React.useRef(props.loadPage)
+  const mountedRef = React.useRef(false)
+  const firstPending = React.useRef(false)
+  loaderRef.current = props.loadPage
+  const currentIdentity = JSON.stringify([props.sessionId, props.path])
+
+  /** @private @author ddj 2026年10月22号 @param args Request identity. @returns Current injected loader response. */
+  function loadPage(args: Parameters<TextPageLoader>[0]): ReturnType<TextPageLoader> {
+    return loaderRef.current(args)
+  }
+  /** @private @author ddj 2026年10月22号 @param state Latest pager snapshot. @returns Publish only while mounted. */
+  function onSnapshot(state: TextPagerState): void {
+    if (!mountedRef.current) return
+    setSnapshot(state)
+    if (!state.loading && firstPending.current) queueMicrotask(loadFirst)
+  }
+
+  /** @private @author ddj 2026年10月22号 @description Start only the new identity's deferred first page, never automatic continuation. */
+  function loadFirst(): void {
+    const pager = pagerRef.current
+    if (!mountedRef.current || !firstPending.current || !pager || pager.getState().loading
+      || (typeof document !== 'undefined' && document.hidden)) return
+    firstPending.current = false
+    void pager.loadNext()
+  }
+
+  /** @private @author ddj 2026年10月22号 @returns Bind identity without replacing the single transport lock. */
+  function mountPager(): () => void {
+    mountedRef.current = true
+    if (!pagerRef.current) pagerRef.current = createTextPager(loadPage, onSnapshot)
+    const pager = pagerRef.current
+    setIdentity(currentIdentity)
+    firstPending.current = true
+    pager.reset({ sessionId: props.sessionId, path: props.path })
+    loadFirst()
+    if (typeof document !== 'undefined') document.addEventListener('visibilitychange', loadFirst)
+    /** @private @author ddj 2026年10月22号 @returns Release retained text and ignore pending responses. */
+    function unmountPager(): void {
+      mountedRef.current = false
+      firstPending.current = false
+      if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', loadFirst)
+      pager.invalidate()
+    }
+    return unmountPager
+  }
+  React.useEffect(mountPager, [props.sessionId, props.path])
+
+  /** @private @author ddj 2026年10月22号 @returns Load exactly one additional page on user intent. */
+  function loadNext(): void {
+    if (typeof document !== 'undefined' && document.hidden) return
+    if (firstPending.current) { loadFirst(); return }
+    void pagerRef.current?.loadNext()
+  }
+
+  const state = identity === currentIdentity ? snapshot : null
+  let status = '正在加载只读文本…'
+  if (state?.error) status = state.error
+  else if (state?.capped) status = '已达预览上限（8 MiB / 50,000 行），请使用外部编辑器查看完整文件'
+  else if (state?.eof) status = '文件末尾 · 只读'
+  else if (state) status = `已读取 ${state.offset.toLocaleString()} / ${state.size.toLocaleString()} 字节 · 只读`
+  if (state?.partialLine) status += ' · 末行尚未完整'
+
+  return React.createElement('section', { className: 'edrv-large-text', 'aria-label': '大文件只读预览' },
+    React.createElement('div', { className: 'edrv-large-text-toolbar' },
+      React.createElement('span', { role: 'status' }, status),
+      React.createElement(Button, { onClick: loadNext,
+        disabled: !state || state.loading || state.eof || state.capped },
+      state?.loading ? '加载中…' : (state?.error ? '重试本段' : '加载下一段'))),
+    React.createElement('pre', { className: 'edrv-large-text-content', tabIndex: 0 }, state?.text ?? ''))
+}

package/src/rpc.ts

@@ -56,6 +56,10 @@ import { markActiveSessions, markOfficialFlags, moveOutSessions, planMoveOut, pu
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
 import type { FileVersions } from './fileVersions.js'
 import { settingsDocPath } from './settingsDocPath.js'
+import { createTextPages } from './textPages.js'
+
+/** Process-local cursor signer; reads must stay on the Host filesystem capability. */
+const readTextPage = createTextPages()
 
 /** cwd → 上次 stale 自动清理时间：全量轮询（EditorView/DiffBadge/Dock 各自 5s）节流，避免每轮都读文件算指纹。 */
 const staleCheckedAt = new Map<string, number>()
@@ -162,7 +166,7 @@ async function readTargetOf(
   ctx: Ctx,
   sc: { session: Session; cwd: string },
   path: string,
-): Promise<ReadTargetOk | { err: string; resolvedPath?: string }> {
+): Promise<ReadTargetOk | { err: string; resolvedPath?: string; code?: 'file-too-large' }> {
   const fs = ctx.get('fs')
   if (!fs) return { err: '缺少 fs' }
   try {
@@ -173,7 +177,7 @@ async function readTargetOf(
       // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
       return { err: '文件不存在', resolvedPath: fs.processPath(target) }
     }
-    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览' }
+    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览', code: 'file-too-large' }
     return { target, fs, info }
   } catch (error) {
     return { err: '读取失败：' + String(error) }
@@ -186,10 +190,10 @@ async function readTargetOf(
  * @param prep readTargetOf 的失败分支
  * @returns { ok:false } 形态载荷
  */
-function targetErrOf(prep: { err: string; resolvedPath?: string }): { ok: false; error: string; resolvedPath?: string } {
-  return prep.resolvedPath !== undefined
-    ? { ok: false, error: prep.err, resolvedPath: prep.resolvedPath }
-    : { ok: false, error: prep.err }
+function targetErrOf(prep: { err: string; resolvedPath?: string; code?: 'file-too-large' }): { ok: false; error: string; resolvedPath?: string; code?: 'file-too-large' } {
+  return { ok: false, error: prep.err,
+    ...(prep.resolvedPath !== undefined ? { resolvedPath: prep.resolvedPath } : {}),
+    ...(prep.code ? { code: prep.code } : {}) }
 }
 
 /**
@@ -699,6 +703,24 @@ export function buildHandlers(
       const results = await applyDecisions(ctx, sc.session, sc.cwd, bucket, Array.isArray(args.items) ? args.items : [])
       return { ok: true, results }
     },
+    /** @author ddj 2026年10月22号 @param args Read-only request. @returns Bounded official range read, or unsupported on older providers; never bypasses Host IO. */
+    'edrv.textPage': async (args) => {
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err, reason: 'read-failed' }
+      try {
+        const target = await resolveTarget(ctx, sc.session, args.path)
+        const fs = ctx.get('fs')
+        if (typeof fs?.readByteRange !== 'function' || typeof fs.stat !== 'function') return readTextPage(undefined, args)
+        // Keys are opaque identities, never decoded into physical paths. Both legacy string and official FsTarget are supported.
+        const targetKey = typeof target === 'string' ? target : (target as { targetKey?: unknown }).targetKey
+        if (typeof targetKey !== 'string') return readTextPage(undefined, args)
+        /** @author ddj 2026年10月22号 @returns Provider metadata used for before/after freshness checks. */
+        function statPage() { return fs.stat(target) }
+        /** @author ddj 2026年10月22号 @param offset Verified cursor position. @param length Bounded byte count. @returns Bytes through the official provider only. */
+        function readRange(offset: number, length: number) { return fs.readByteRange(target, { offset, length }) }
+        return readTextPage({ identity: JSON.stringify([sc.cwd, targetKey]), stat: statPage, readRange }, args)
+      } catch (error) { return { ok: false, error: '读取失败：' + String(error), reason: 'read-failed' } }
+    },
     'edrv.read': async (args) => {
       const settingsTarget = settingsTargetOf(ctx, args.path)
       if (settingsTarget && args.encoding !== 'base64') {
@@ -735,7 +757,7 @@ export function buildHandlers(
           const content = Buffer.from(bytes).toString('base64')
           return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(prep.info.version ?? '') }
         }
-        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
+        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览', code: 'file-too-large' }
         const content = await prep.fs.readText(prep.target)
         return { ok: true, content, size: content.length, version: String(prep.info.version ?? '') }
       } catch (error) {

package/src/shared/rpc.ts

@@ -372,6 +372,7 @@ export interface RpcRequestMap {
   'edrv.accept': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.reject': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.decideBatch': { sessionId?: string; items: DecideItem[] }
+  'edrv.textPage': import('./textPages.js').TextPageArgs
   'edrv.read': { sessionId?: string; path: string; encoding?: 'base64' }
   'edrv.readBinary': { sessionId?: string; path: string }
   'edrv.versions': { sessionId?: string; paths: string[] }
@@ -540,6 +541,7 @@ export interface RpcOkMap {
   'edrv.accept': { record: RecordView }
   'edrv.reject': { record: RecordView }
   'edrv.decideBatch': { results: DecideResult[] }
+  'edrv.textPage': Extract<import('./textPages.js').TextPageResult, { ok: true }>
   'edrv.read': { content: string; size: number; encoding?: 'base64'; mime?: string; version?: string }
   'edrv.readBinary': { binary: BinaryReadPayload }
   'edrv.versions': { items: FileVersionItem[] }
@@ -698,7 +700,7 @@ export interface RpcOkMap {
 /** 统一响应：{ok:true, ...payload} 或 {ok:false, error}。 */
 export type RpcResult<M extends RpcMethod> =
   | ({ ok: true } & RpcOkMap[M])
-  | { ok: false; error: string }
+  | { ok: false; error: string; code?: 'file-too-large'; reason?: Extract<import('./textPages.js').TextPageResult, { ok: false }>['reason'] }
 
 /** 每个方法的 handler 签名（host 分发表与 client 类型检查共用）。 */
 export type RpcHandler<M extends RpcMethod> = (

package/src/shared/snippets.ts

@@ -128,7 +128,7 @@ export const SNIPPET_LANGUAGES: readonly string[] = [
   'c', 'cpp', 'csharp', 'css', 'dart', 'dockerfile', 'go', 'html', 'ini', 'java',
   'javascript', 'json', 'jsonc', 'kotlin', 'less', 'lua', 'markdown', 'mdx', 'php',
   'plaintext', 'powershell', 'python', 'ruby', 'rust', 'scss', 'shell', 'sql',
-  'swift', 'typescript', 'xml', 'yaml',
+  'swift', 'systemverilog', 'tcl', 'typescript', 'verilog', 'xml', 'yaml',
 ]
 
 /** 语言 id → 展示名（仅收录写法与 id 明显不同的；未收录的原样返回）。 */

package/src/shared/textPages.ts

@@ -0,0 +1,28 @@
+/** Bounded, read-only text paging protocol. @author ddj 2026年10月22号 */
+export const TEXT_PAGE_BYTES = 256 * 1024
+export const TEXT_VIEW_BYTES = 8 * 1024 * 1024
+export const TEXT_VIEW_LINES = 50_000
+
+export interface TextPageArgs {
+  sessionId?: string
+  path: string
+  cursor?: string
+}
+
+export type TextPageResult = {
+  ok: true
+  text: string
+  version: string
+  /** Absolute byte offset following this page, including the initial BOM. */
+  offset: number
+  size: number
+  eof: boolean
+  nextCursor: string | null
+  encoding: 'utf-8'
+  /** True when this non-final page ends in the middle of a logical line. */
+  partialLine: boolean
+} | {
+  ok: false
+  reason: 'unsupported' | 'invalid-cursor' | 'stale' | 'not-text' | 'read-failed'
+  error: string
+}

package/src/textPages.ts

@@ -0,0 +1,149 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { TEXT_PAGE_BYTES } from './shared/textPages.js'
+import type { TextPageArgs, TextPageResult } from './shared/textPages.js'
+
+/** Only an authorized Host adapter may supply this capability; never use raw fs as fallback. */
+export interface TextPageSource {
+  /** Authorized workspace + canonical target identity; re-authorize every request before supplying this source. */
+  identity: string
+  stat(): Promise<{ version: string; size: number; type: string } | undefined>
+  readRange(offset: number, length: number): Promise<Uint8Array>
+}
+
+interface PageCursor {
+  identity: string
+  sessionId: string
+  path: string
+  version: string
+  offset: number
+  pendingCR: boolean
+}
+
+/**
+ * Create a Host-owned pager with process-local authenticated cursors.
+ * @public @author ddj 2026年10月22号
+ * @returns A bounded reader requiring an independently authorized range capability.
+ */
+export function createTextPages() {
+  const secret = randomBytes(32)
+
+  /** @private @author ddj 2026年10月22号 @param payload Authenticated state. @returns Signed cursor. */
+  function signCursor(payload: PageCursor): string {
+    const body = Buffer.from(JSON.stringify(payload)).toString('base64url')
+    return body + '.' + createHmac('sha256', secret).update(body).digest('base64url')
+  }
+
+  /** @private @author ddj 2026年10月22号 @param token Untrusted cursor. @returns Verified state or null. */
+  function parseCursor(token: string): PageCursor | null {
+    if (typeof token !== 'string' || token.length > 8192) return null
+    const parts = token.split('.')
+    if (parts.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(parts[0]!)) return null
+    const signature = Buffer.from(parts[1]!, 'base64url')
+    const expected = createHmac('sha256', secret).update(parts[0]!).digest()
+    if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return null
+
+    try {
+      const payload = JSON.parse(Buffer.from(parts[0]!, 'base64url').toString('utf8')) as PageCursor
+      if (typeof payload.identity !== 'string' || typeof payload.version !== 'string'
+        || typeof payload.sessionId !== 'string' || typeof payload.path !== 'string'
+        || typeof payload.pendingCR !== 'boolean' || !Number.isSafeInteger(payload.offset)
+        || payload.offset <= 0) return null
+      return payload
+    } catch { return null }
+  }
+
+  /**
+   * Read at most 256 KiB, validating freshness before and after IO.
+   * @public @author ddj 2026年10月22号
+   * @param source Authorized range capability; absent means unsupported.
+   * @param args Request identity and optional signed cursor.
+   * @returns Strict UTF-8 text or an explicit fail-closed result; never partial success on mutation.
+   */
+  async function readTextPage(source: TextPageSource | undefined, args: TextPageArgs): Promise<TextPageResult> {
+    if (!source) return failure('unsupported', 'Host does not expose authorized range reads')
+    const cursor = args.cursor === undefined ? undefined : parseCursor(args.cursor)
+    if (cursor === null || (cursor && (cursor.identity !== source.identity
+      || cursor.sessionId !== (args.sessionId ?? '') || cursor.path !== args.path))) {
+      return failure('invalid-cursor', 'Cursor does not belong to this file and session')
+    }
+
+    try {
+      const before = await source.stat()
+      if (!before || before.type !== 'file' || typeof before.version !== 'string'
+        || !Number.isSafeInteger(before.size) || before.size < 0) {
+        return failure('unsupported', 'Regular file size and opaque version are required')
+      }
+      if (cursor && (cursor.version !== before.version || cursor.offset >= before.size)) {
+        return failure('stale', 'File changed; restart text preview')
+      }
+      const offset = cursor?.offset ?? 0
+      const length = Math.min(TEXT_PAGE_BYTES, before.size - offset)
+      const bytes = await source.readRange(offset, length)
+      const after = await source.stat()
+      if (!after || after.version !== before.version || after.size !== before.size || after.type !== 'file') {
+        return failure('stale', 'File changed during text read')
+      }
+      if (!(bytes instanceof Uint8Array) || bytes.byteLength !== length) {
+        return failure('read-failed', 'Range reader returned an incomplete or oversized page')
+      }
+      return decodePage(bytes, before, offset, cursor?.pendingCR ?? false, args, source.identity, signCursor)
+    } catch (error) {
+      return failure('read-failed', String(error))
+    }
+  }
+
+  return readTextPage
+}
+
+/** @private @author ddj 2026年10月22号 @param reason Failure discriminator. @param error User-visible error. @returns Failure result. */
+function failure(reason: Extract<TextPageResult, { ok: false }>['reason'], error: string): TextPageResult {
+  return { ok: false, reason, error }
+}
+
+/**
+ * Keep an incomplete final UTF-8 sequence for a bounded re-read on the next page.
+ * @private @author ddj 2026年10月22号
+ * @param bytes Raw page. @returns Complete prefix length; invalid sequences remain for fatal decoding.
+ */
+function utf8Prefix(bytes: Uint8Array): number {
+  let start = bytes.length - 1
+  while (start >= 0 && (bytes[start]! & 0xc0) === 0x80) start--
+  if (start < 0) return bytes.length
+  const lead = bytes[start]!
+  let width = 1
+  if (lead >= 0xc2 && lead <= 0xdf) width = 2
+  else if (lead >= 0xe0 && lead <= 0xef) width = 3
+  else if (lead >= 0xf0 && lead <= 0xf4) width = 4
+  return bytes.length - start < width ? start : bytes.length
+}
+
+/**
+ * Decode one page preserving original line endings without buffering a long line.
+ * @private @author ddj 2026年10月22号
+ * @param bytes Raw page. @param info File snapshot. @param offset Current offset.
+ * @param pendingCR Previous trailing CR. @param args Request identity. @param identity Authorized target identity.
+ * @param signCursor Host cursor signer. @returns Page or strict decoding failure.
+ */
+function decodePage(
+  bytes: Uint8Array, info: { size: number; version: string }, offset: number, pendingCR: boolean,
+  args: TextPageArgs, identity: string, signCursor: (cursor: PageCursor) => string,
+): TextPageResult {
+  const finalRange = offset + bytes.length === info.size
+  const consumed = finalRange ? bytes.length : utf8Prefix(bytes)
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, consumed))
+  } catch { return failure('not-text', 'File is not valid UTF-8') }
+  if (text.includes('\0')) return failure('not-text', 'Binary text preview is unsupported')
+  if (offset === 0 && text.startsWith('\uFEFF')) text = text.slice(1)
+  if (pendingCR) text = '\r' + text
+
+  const nextOffset = offset + consumed
+  const eof = nextOffset === info.size
+  const trailingCR = !eof && text.endsWith('\r')
+  if (trailingCR) text = text.slice(0, -1)
+  const nextCursor = eof ? null : signCursor({ identity, sessionId: args.sessionId ?? '', path: args.path,
+    version: info.version, offset: nextOffset, pendingCR: trailingCR })
+  return { ok: true, text, version: info.version, offset: nextOffset, size: info.size, eof, nextCursor,
+    encoding: 'utf-8', partialLine: !eof && !/[\r\n]$/.test(text) }
+}