dsh-vscode-mode 0.17.0 → 0.19.0

package/src/client/sidebar/panels/FileExplorer.ts

@@ -28,7 +28,7 @@ import { useExplorerSvn } from './useExplorerSvn.js'
 import { useExplorerReveal, treeRevealPath } from './useExplorerReveal.js'
 import type { SidebarCtx } from '../types.js'
 
-const DIR_CAP = 4000
+import { flattenTree, treeAnchorTop, treeRevealTop, treeWindow, TREE_ROW_HEIGHT } from './treeWindow.js'
 const SAVE_DEBOUNCE_MS = 300
 const FOLLOW_INTERVAL_MS = 10_000
 const PREFETCH_MAX = 4
@@ -126,7 +126,8 @@ export function FileExplorer(props) {
   const saveTimerRef = React.useRef(null)
   const loadDirRef = React.useRef(null)
   const refreshRef = React.useRef(null)
-  const treeRef = React.useRef(null) // 目录树容器（定位时按 data-edrv-path 查行）
+  const treeRef = React.useRef(null) // 唯一目录树滚动容器
+  const [viewport, setViewport] = React.useState({ scope, top: 0, height: 0 })
   const reloadDirRef = React.useRef(null) // loadDir 最新闭包（文件变化监听读取，防陈旧闭包）
   const changedTimerRef = React.useRef(null) // 文件变化合并去抖计时器
   const changedRelRef = React.useRef(new Set()) // 待重列的相对目录集合（去抖窗口内合并）
@@ -338,8 +339,6 @@ export function FileExplorer(props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // 在恢复工作区展开状态之后跟随活动文件；隐藏期间目标由编辑器保留，重新挂载时兑现。
-  const { revealPath } = useExplorerReveal({ scope, activePath, treeRef, prepare: prepareReveal })
   const activeTreePath = treeRevealPath(activePath)
 
   // 10s 轻量跟随：已展开目录后台刷新（命中 host 索引，近零成本），树跟随 agent 写入
@@ -355,24 +354,71 @@ export function FileExplorer(props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [scope])
 
-  /** @private @author ddj 2026年10月10号 @returns Expanded tree descriptors; icon refreshes never re-walk the tree. */
-  function flatten() {
-    const result = []
-    /** @private @author ddj 2026年10月10号 @param rel Directory. @param depth Indent level. Appends only expanded rows and placeholders. */
-    function visit(rel, depth) {
-      const entries = dirs[rel] ?? entriesCacheGet(scope, rel)
-      if (!entries) { result.push({ key: rel + ':loading', depth, text: loading[rel] ? '加载中…' : '无法加载' }); return }
-      for (const e of entries) {
-        const isDir = e.type === 'directory', isOpen = expanded[e.path] === true
-        result.push({ key: e.path, e, depth, isDir, isOpen })
-        if (isDir && isOpen) visit(e.path, depth + 1)
-      }
-      if (entries.length >= DIR_CAP) result.push({ key: rel + ':cap', depth, text: '目录条目过多，仅显示前 ' + DIR_CAP + ' 项' })
+  /** @private @author ddj 2026年10月22号 @returns Complete expanded model; icon-only updates do not flatten again. */
+  function flatten() { return flattenTree(entriesOf, expanded, loading) }
+  const treeRows = React.useMemo(flatten, [dirs, expanded, loading, scope])
+  const previousRows = React.useRef({ scope, rows: treeRows })
+  let anchoredTop = 0
+  if (viewport.scope === scope) {
+    anchoredTop = viewport.top
+    if (previousRows.current.scope === scope && previousRows.current.rows !== treeRows) {
+      anchoredTop = treeAnchorTop(previousRows.current.rows, treeRows, viewport.top)
     }
-    visit('', 0)
-    return result
   }
-  const treeRows = React.useMemo(flatten, [dirs, expanded, loading, scope])
+  const currentViewport = { top: anchoredTop, height: viewport.height }
+  const windowRows = treeWindow(treeRows.length, currentViewport)
+
+  /** @private @author ddj 2026年10月22号 Read current geometry after scroll, resize or scope restoration. */
+  function measureTree() {
+    const host = treeRef.current
+    if (!host || host.clientHeight <= 0) return
+    setViewport({ scope, top: host.scrollTop, height: host.clientHeight })
+  }
+  const scrollFrame = React.useRef(null)
+  /** @private @author ddj 2026年10月22号 Coalesce high-frequency scrolling into one measured render per frame. */
+  function scrollTree() {
+    if (scrollFrame.current !== null) return
+    scrollFrame.current = requestAnimationFrame(readScroll)
+  }
+  /** @private @author ddj 2026年10月22号 Read only after the pending animation frame fires. */
+  function readScroll() { scrollFrame.current = null; measureTree() }
+  /** @private @author ddj 2026年10月22号 @returns Resize observer and pending frame cleanup. Keep hidden trees measurable when shown. */
+  function watchTree() {
+    const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(measureTree) : null
+    if (treeRef.current) observer?.observe(treeRef.current)
+    measureTree()
+    /** @private @author ddj 2026年10月22号 Stop all viewport callbacks owned by this scope. */
+    function cleanup() {
+      observer?.disconnect()
+      if (scrollFrame.current !== null) cancelAnimationFrame(scrollFrame.current)
+      scrollFrame.current = null
+    }
+    return cleanup
+  }
+  React.useLayoutEffect(watchTree, [scope])
+  /** @private @author ddj 2026年10月22号 Clamp actual scroll after collapse, filtering, or workspace switch. */
+  function clampTree() {
+    const host = treeRef.current
+    previousRows.current = { scope, rows: treeRows }
+    if (!host || host.clientHeight <= 0) return
+    if (host.scrollTop !== windowRows.top) host.scrollTop = windowRows.top
+    if (viewport.scope !== scope || viewport.top !== windowRows.top) {
+      setViewport({ scope, top: windowRows.top, height: host.clientHeight })
+    }
+  }
+  React.useLayoutEffect(clampTree, [scope, windowRows.top, treeRows])
+  /** @private @author ddj 2026年10月22号 @param path Requested file. @returns Whether its complete model row is available. */
+  function locateTree(path) {
+    const host = treeRef.current
+    if (!host) return false
+    const top = treeRevealTop(treeRows, path, { top: host.scrollTop, height: host.clientHeight })
+    if (top === null) return false
+    host.scrollTop = top
+    setViewport({ scope, top, height: host.clientHeight })
+    return true
+  }
+  // 定位由完整数据索引兑现，目标无需预先挂载 DOM；异步祖先加载后 hook 会重试。
+  const { revealPath } = useExplorerReveal({ scope, activePath, treeRef, prepare: prepareReveal, locate: locateTree })
   /** @private @author ddj 2026年10月10号 @returns Stable RPC row projection, independent of icon-only renders. */
   function projectRows() { return treeRows.filter((row) => row.e).map((row) => ({ path: row.e.path, isDir: row.isDir })) }
   const svnRows = React.useMemo(projectRows, [treeRows])
@@ -384,10 +430,10 @@ export function FileExplorer(props) {
   /** @private @author ddj 2026年10月10号 @param path Row path. @param type Entry type. @param event Context trigger. */
   function contextRow(path, type, event) {
     event.preventDefault(); event.stopPropagation()
-    setMenu({ x: event.clientX, y: event.clientY, target: { path, type } })
+    setMenu({ scope, x: event.clientX, y: event.clientY, target: { path, type } })
   }
   const onSelect = React.useCallback((path, isDir) => selectRef.current(path, isDir), [])
-  const onContext = React.useCallback(contextRow, [])
+  const onContext = React.useCallback(contextRow, [scope])
   const rootName = root ? String(root).split(/[\\/]/).pop() || root : ''
 
   /** @private @author ddj 2026年10月10号 @param row Flat descriptor. @returns Memo row; unaffected status objects retain identity. */
@@ -405,10 +451,14 @@ export function FileExplorer(props) {
     ev.preventDefault()
     ev.stopPropagation()
     if (!ev.currentTarget.contains(ev.target)) return
-    setMenu({ x: ev.clientX, y: ev.clientY, target: { path: '', type: 'directory' } })
+    setMenu({ scope, x: ev.clientX, y: ev.clientY, target: { path: '', type: 'directory' } })
   }
+  const menuValid = menu?.scope === scope && (menu.target.path === '' || treeRows.some((row) => row.e?.path === menu.target.path))
+  /** @private @author ddj 2026年10月22号 Close stale path menus instead of rebinding recycled rows. */
+  function closeLostMenu() { if (menu && !menuValid) setMenu(null) }
+  React.useEffect(closeLostMenu, [menu, menuValid])
   // 当前右键目标的可视菜单项（构建时过滤/排序，registry 变化下次打开生效）。
-  const menuEntries = menu
+  const menuEntries = menuValid
     ? buildTreeMenu(ctx?.fileMenuItems, menu.target, ctx).map((item) => ({
         id: item.id,
         label: item.label,
@@ -443,13 +493,16 @@ export function FileExplorer(props) {
       }, '↓') : null,
       React.createElement('button', { className: 'edrv-side-btn', title: '刷新目录树', onClick: () => emitRefresh({ scope, kind: 'unknown' }) }, refreshIconEl())),
     svn.message ? React.createElement('div', { className: 'edrv-tree-status', role: 'status' }, svn.message) : null,
-    React.createElement('div', { className: 'edrv-tree', ref: treeRef },
-      (errorText
+    (errorText
         ? React.createElement('div', { className: 'edrv-tree-error' },
             React.createElement('span', null, String(errorText)),
             React.createElement('button', { className: 'edrv-side-btn', onClick: () => emitRefresh({ scope, kind: 'unknown' }) }, '重试'))
         : null),
-      treeRows.map(renderRow)),
+    React.createElement('div', { className: 'edrv-tree edrv-tree-virtual', ref: treeRef, onScroll: scrollTree },
+      React.createElement('div', { 'aria-hidden': true, style: { height: windowRows.start * TREE_ROW_HEIGHT } }),
+      treeRows.slice(windowRows.start, windowRows.end).map(renderRow),
+      React.createElement('div', { 'aria-hidden': true, style: { height: (treeRows.length - windowRows.end) * TREE_ROW_HEIGHT } })),
+
     (menu && menuEntries.length
       ? React.createElement(ContextMenu, { x: menu.x, y: menu.y, entries: menuEntries, onClose: () => setMenu(null) })
       : null))

package/src/client/sidebar/panels/SvnPanel.ts

@@ -484,7 +484,7 @@ export function SvnPanel(props) {
   const [remote, setRemote] = React.useState(null)
   const [remoteBusy, setRemoteBusy] = React.useState(false)
   // W2-5：配对候选的文件大小（path → size|null）与成对结果
-  const [sizes, setSizes] = React.useState({})
+  const [sizeSnapshot, setSizes] = React.useState(null)
   // 渐进渲染预算：过滤/作用域变化时重置，避免过滤后仍停留在旧的大预算
   const [renderLimit, setRenderLimit] = React.useState(RENDER_STEP)
   // ctx 由编辑区每轮渲染重建；行动作回调改读 ref 取最新值，回调身份才能稳定（行 React.memo 生效前提）
@@ -606,14 +606,30 @@ export function SvnPanel(props) {
     () => [...missingEntries, ...unversionedEntries].slice(0, FILE_SIZES_CAP).map((entry) => entry.path),
     [missingEntries, unversionedEntries],
   )
-  const candidateKey = React.useMemo(() => requested.join('\n'), [requested])
-  const pairsNeeded = missingEntries.length > 0 && unversionedEntries.length > 0
+  const candidateKey = JSON.stringify(requested)
+  const sizeOwner = JSON.stringify([scope, sessionId, candidateKey, managed])
+  const sizeOwnerRef = React.useRef(sizeOwner)
+  sizeOwnerRef.current = sizeOwner
+  const sizes = sizeSnapshot?.owner === sizeOwner ? sizeSnapshot.table : {}
+  const pairsNeeded = managed && missingEntries.length > 0 && unversionedEntries.length > 0
   const pairsKnown = pairsNeeded && requested.every((path) => path in sizes)
-  React.useEffect(() => {
-    if (pairsKnown || !requested.length) return
-    void svnFileSizes(sessionId, requested).then((table) => setSizes(table))
-    // requested 内容由 candidateKey 代理：同 key 必同内容，闭包取旧数组无碍（去重语义与旧 join 依赖一致）
-  }, [pairsKnown, candidateKey, sessionId]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /** @private @author ddj 2026年10月22号 @returns Cleanup invalidating this request. @description Keep sizes scoped to this candidate generation; failures do not retry in a render loop. */
+  function loadPairSizes() {
+    if (!pairsNeeded || !requested.length) return
+    let disposed = false
+    /** @author ddj 2026年10月22号 @param table Candidate sizes. @description Publish only to the current request owner. */
+    function acceptSizes(table) {
+      if (!disposed && sizeOwnerRef.current === sizeOwner) setSizes({ owner: sizeOwner, table })
+    }
+    /** @author ddj 2026年10月22号 @description Failed reads leave pairing unknown without breaking the changes list. */
+    function ignoreFailure() { /* A future candidate/session change may retry. */ }
+    /** @author ddj 2026年10月22号 @description Revoke this request on dependency change or unmount. */
+    function cancelSizes() { disposed = true }
+    void svnFileSizes(sessionId, requested).then(acceptSizes, ignoreFailure)
+    return cancelSizes
+  }
+  React.useEffect(loadPairSizes, [sizeOwner, pairsNeeded])
 
   const pairNoteOf = React.useMemo(() => {
     if (!pairsKnown) return {}

package/src/client/sidebar/panels/index.ts

@@ -10,9 +10,8 @@ import { IconBranchOutline16, IconFolderOpenOutline16, IconListPenOutline16, Ico
 import { dapStore } from '../../dap/store.js'
 import { FileExplorer } from './FileExplorer.js'
 import { SearchPanel } from './SearchPanel.js'
-import { RulesPanel } from './RulesPanel.js'
+import { LazyPanel } from '../../lazyPanel.js'
 import { SvnPanel } from './SvnPanel.js'
-import { DebugPanel } from './DebugPanel.js'
 import type { SidebarPanelDef, SidebarCtx } from '../types.js'
 
 /**
@@ -57,7 +56,7 @@ export function createRulesPanel(): SidebarPanelDef {
     title: '规则',
     icon: IconListPenOutline16,
     order: 20,
-    render: (ctx: SidebarCtx) => React.createElement(RulesPanel, { ctx }),
+    render: (ctx: SidebarCtx) => React.createElement(LazyPanel, { key: 'rules', panel: 'rules', ctx }),
   }
 }
 
@@ -113,6 +112,6 @@ export function createDebugPanel(): SidebarPanelDef {
     icon: '🐞',
     order: 22,
     badge: () => (dapStore.getSnapshot().phase === 'paused' ? 1 : null),
-    render: (ctx: SidebarCtx) => React.createElement(DebugPanel, { ctx }),
+    render: (ctx: SidebarCtx) => React.createElement(LazyPanel, { key: 'debug', panel: 'debug', ctx }),
   }
 }

package/src/client/sidebar/panels/treeWindow.ts

@@ -0,0 +1,106 @@
+/** File explorer fixed-height row model. @author ddj 2026年10月22号 */
+import type { TreeEntry } from '../../../shared/rpc.js'
+import { updateRange } from '../../ui/svnUpdateModel.js'
+
+/** Fixed geometry shared with file and loading row CSS. */
+export const TREE_ROW_HEIGHT = 24
+
+export interface TreeRow {
+  key: string
+  depth: number
+  e?: TreeEntry
+  isDir?: boolean
+  isOpen?: boolean
+  text?: string
+}
+
+export interface TreeViewport {
+  top: number
+  height: number
+}
+
+/**
+ * @public @author ddj 2026年10月22号
+ * @description Preserve the first visible path when rows above it expand or collapse.
+ * @param previous Previous complete model.
+ * @param rows New complete model.
+ * @param top Previous scroll offset.
+ * @returns Anchored offset, or original offset for subsequent clamping if path disappeared.
+ */
+export function treeAnchorTop(previous: TreeRow[], rows: TreeRow[], top: number): number {
+  const index = Math.floor(Math.max(0, top) / TREE_ROW_HEIGHT)
+  const anchor = previous[index]?.key
+  if (!anchor) return top
+  const nextIndex = rows.findIndex((row) => row.key === anchor)
+  if (nextIndex < 0) return top
+  return nextIndex * TREE_ROW_HEIGHT + top % TREE_ROW_HEIGHT
+}
+
+/**
+ * @public @author ddj 2026年10月22号
+ * @description Flatten all expanded entries in their supplied order, including metadata files.
+ * @param entriesOf Directory snapshot lookup; null means unavailable.
+ * @param expanded Current directory expansion flags.
+ * @param loading Current loading flags.
+ * @returns Complete row model, independent of viewport mounting.
+ */
+export function flattenTree(entriesOf: (rel: string) => TreeEntry[] | null,
+  expanded: Record<string, boolean>, loading: Record<string, boolean>): TreeRow[] {
+  const rows: TreeRow[] = []
+  const pending: { rel: string; depth: number; entry?: TreeEntry }[] = [{ rel: '', depth: 0 }]
+  while (pending.length) {
+    const current = pending.pop()!
+    const entry = current.entry
+    if (entry) {
+      const isDir = entry.type === 'directory'
+      const isOpen = expanded[entry.path] === true
+      rows.push({ key: entry.path, e: entry, depth: current.depth, isDir, isOpen })
+      if (isDir && isOpen) pending.push({ rel: entry.path, depth: current.depth + 1 })
+      continue
+    }
+
+    const entries = entriesOf(current.rel)
+    if (!entries) {
+      rows.push({ key: current.rel + ':loading', depth: current.depth,
+        text: loading[current.rel] ? '加载中…' : '无法加载' })
+      continue
+    }
+    // Stack reverses insertion order; push backwards to preserve host sorting.
+    for (let index = entries.length - 1; index >= 0; index--) {
+      pending.push({ rel: current.rel, depth: current.depth, entry: entries[index] })
+    }
+  }
+  return rows
+}
+
+/**
+ * @public @author ddj 2026年10月22号
+ * @description Clamp scroll state before reusing the existing fixed-height range calculation.
+ * @param count Complete row count.
+ * @param viewport Latest scroll position and measured viewport height.
+ * @returns Clamped scroll offset and overscanned exclusive row range.
+ */
+export function treeWindow(count: number, viewport: TreeViewport) {
+  const height = Math.max(0, viewport.height)
+  const top = Math.min(Math.max(0, viewport.top), Math.max(0, count * TREE_ROW_HEIGHT - height))
+  return { top, ...updateRange(count, top, height, TREE_ROW_HEIGHT) }
+}
+
+/**
+ * @public @author ddj 2026年10月22号
+ * @description Locate an unmounted row using model indices, without querying row DOM.
+ * @param rows Complete flattened model.
+ * @param path Requested relative file path.
+ * @param viewport Current viewport geometry.
+ * @returns New scroll offset, or null while ancestors/viewport are unavailable.
+ */
+export function treeRevealTop(rows: TreeRow[], path: string, viewport: TreeViewport): number | null {
+  if (viewport.height <= 0) return null
+  const index = rows.findIndex((row) => row.e?.path === path)
+  if (index < 0) return null
+  const current = treeWindow(rows.length, viewport).top
+  const rowTop = index * TREE_ROW_HEIGHT
+  if (rowTop >= current && rowTop + TREE_ROW_HEIGHT <= current + viewport.height) return current
+  return treeWindow(rows.length, { top: rowTop - (viewport.height - TREE_ROW_HEIGHT) / 2,
+    height: viewport.height }).top
+}

package/src/client/sidebar/panels/useExplorerReveal.ts

@@ -27,6 +27,8 @@ interface RevealOptions {
   activePath: string | null
   treeRef: React.RefObject<HTMLElement>
   prepare: (path: string) => void
+  /** Optional virtual-list locator; success does not depend on mounted row DOM. */
+  locate?: (path: string) => boolean
 }
 interface RevealTarget {
   scope: string
@@ -60,12 +62,13 @@ export function useExplorerReveal(options: RevealOptions) {
     setTarget(next)
     if (next) current.prepare(next.path)
   }
-  /** @private @author ddj 2026年10月14号 Attempts the latest target after row commit or container resize. Consumes only a successful, current request. */
+  /** @private @author ddj 2026年10月22号 Attempts virtual data-index location or the original mounted-row fallback after commit/resize; consumes only a successful current request. */
   function tryReveal(): void {
     const next = pending.current
     const current = latest.current
     if (!next || next.scope !== current.scope || next.active !== current.activePath) return
-    if (!revealTreeRow(current.treeRef.current, next.path)) return
+    const located = current.locate ? current.locate(next.path) : revealTreeRow(current.treeRef.current, next.path)
+    if (!located) return
     pending.current = null
     setRevealPath(next.path)
     clearHighlight()

package/src/client/sidebar/registry.ts

@@ -28,8 +28,11 @@ function panelRegister(entries: Map<string, SidebarPanelDef>, notify: () => void
 export function createSidebarPanelRegistry(): SidebarPanelRegistry {
   const entries = new Map<string, SidebarPanelDef>()
   const listeners = new Set<() => void>()
+  /** @private @author ddj 2026年10月22号 @description Isolate subscribers and snapshot notification membership against reentrant changes. */
   const notify = (): void => {
-    for (const listener of listeners) listener()
+    for (const listener of [...listeners]) {
+      try { listener() } catch { /* One extension must not block other subscribers or registration teardown. */ }
+    }
   }
   const list = (): readonly SidebarPanelDef[] =>
     [...entries.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100))

package/src/client/state/modelWarmer.ts

@@ -0,0 +1,198 @@
+/**
+ * dsh-vscode-mode client — Monaco model 预热调度层。
+ *
+ * 背景：Monaco 的 GotoDefinitionAtPositionEditorContribution 在 Ctrl+hover 渲染定义链接
+ * 预览时，对目标的 edrv:// uri 调 textModelResolverService.createModelReference 后
+ * **只挂 then、没有 catch**；目标文件若从未在本会话打开过，该 uri 没有已注册 model，
+ * createModelReference 直接 reject("Model not found")，成为未捕获的 promise 异常。
+ * 本构建的 vendored Monaco 也没有 registerTextModelContentProvider 可供惰性喂内容，
+ * 因此修法是在 provideDefinition 返回前把目标 model 建出来（预热）。
+ *
+ * 本模块只负责「让某路径的 model 存在」这件事的调度：安装/卸载实现、并发单飞、
+ * 失败冷却与等待上限。真正建 model 的实现由 EditorView 注入（它才持有 monaco 与文档缓存）。
+ * 纯逻辑，不依赖 monaco，可单测。
+ * 作者 ddj 2026年10月20号
+ */
+
+// --region 常量与状态
+
+/** 单次预热调用的等待上限：超过即放行 hover（预热仍在后台继续）。 */
+export const WARM_TIMEOUT_MS = 400
+
+/** 预热失败后该路径的冷却窗口，避免每次 hover 都重试同一失败目标。 */
+export const WARM_COOLDOWN_MS = 10_000
+
+/** 冷却表条目上限（超出按插入序丢最旧），防长会话里无限增长。 */
+export const WARM_COOLDOWN_CAP = 64
+
+/** 预热实现：给定工作区相对路径，成功让 model 存在则返回 true。 */
+export type WarmImpl = (path: string) => Promise<boolean>
+
+/** 当前安装的预热实现（EditorView 挂载时注入，未挂载则为 null）。 */
+let impl: WarmImpl | null = null
+/** path → 进行中的预热（单飞：连续 hover 同一目标只读一次盘）。 */
+const inFlight = new Map<string, Promise<boolean>>()
+/** path → 冷却截止时间戳（毫秒）。 */
+const cooled = new Map<string, number>()
+// --endregion
+
+// --region 状态维护
+
+/**
+ * 清空进行中/冷却状态（安装或卸载实现时复位，避免跨实现串味）。
+ * @author ddj 2026年10月20号
+ */
+function resetWarmerState(): void {
+  inFlight.clear()
+  cooled.clear()
+}
+
+/**
+ * 该路径是否处于失败冷却窗口内（过期的顺手清掉）。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径
+ * @returns 仍在冷却中返回 true
+ */
+function isCooling(path: string): boolean {
+  const until = cooled.get(path)
+  if (until === undefined) return false
+  if (until > Date.now()) return true
+
+  cooled.delete(path)
+  return false
+}
+
+/**
+ * 记录一次失败冷却，并把冷却表裁剪到上限以内。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径
+ */
+function coolDown(path: string): void {
+  cooled.delete(path)
+  cooled.set(path, Date.now() + WARM_COOLDOWN_MS)
+
+  while (cooled.size > WARM_COOLDOWN_CAP) {
+    const oldest = cooled.keys().next()
+    if (oldest.done) break
+
+    cooled.delete(oldest.value)
+  }
+}
+
+/**
+ * 结算一次预热：清 inFlight（仅当仍是自己那条）、按结果维护冷却。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径
+ * @param run 该次预热的 promise（用于识别是否已被更新的一次替换）
+ * @param ok 实现返回的成功与否
+ */
+function settleWarm(path: string, run: Promise<boolean>, ok: boolean): void {
+  if (inFlight.get(path) === run) inFlight.delete(path)
+  if (ok) {
+    cooled.delete(path)
+    return
+  }
+
+  coolDown(path)
+}
+// --endregion
+
+// --region 底层预热
+
+/**
+ * 启动一次底层预热：登记 inFlight、把实现异常折叠成 false（绝不向调用方抛）。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径
+ * @param fn 预热实现
+ * @returns 永不 reject 的布尔 promise（已登记到 inFlight）
+ */
+function startWarm(path: string, fn: WarmImpl): Promise<boolean> {
+  const run = Promise.resolve()
+    .then(() => fn(path))
+    .then(
+      (ok) => ok === true,
+      () => false,
+    )
+
+  inFlight.set(path, run)
+  run.then((ok) => settleWarm(path, run, ok))
+  return run
+}
+
+/**
+ * 给底层预热挂一个等待上限：超时只是本次调用放行，底层继续跑（仍可能建成 model
+ * 惠及下一次 hover），因此超时既不取消 promise，也不提前摘掉 inFlight。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径
+ * @param run 底层预热 promise（永不 reject）
+ * @returns 最多 WARM_TIMEOUT_MS 内结算的布尔结果
+ */
+function withTimeout(path: string, run: Promise<boolean>): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+
+    const finish = (ok: boolean): void => {
+      if (settled) return
+
+      settled = true
+      if (timer) clearTimeout(timer)
+      resolve(ok)
+    }
+
+    timer = setTimeout(() => {
+      coolDown(path)
+      finish(false)
+    }, WARM_TIMEOUT_MS)
+
+    run.then(finish, () => finish(false))
+  })
+}
+// --endregion
+
+// --region 安装与卸载
+
+/**
+ * 安装预热实现（EditorView 挂载时调用；传 null 视同卸载）。
+ * @author ddj 2026年10月20号
+ * @param fn 预热实现，或 null 表示卸载
+ */
+export function setModelWarmer(fn: WarmImpl | null): void {
+  impl = typeof fn === 'function' ? fn : null
+  if (!impl) resetWarmerState()
+}
+
+/**
+ * 卸载预热实现：仅当传入的仍是当前实现才清（防卸载竞态误清新挂载的实现）。
+ * @author ddj 2026年10月20号
+ * @param fn 当初安装的实现
+ */
+export function clearModelWarmer(fn: WarmImpl): void {
+  if (impl !== fn) return
+
+  impl = null
+  resetWarmerState()
+}
+// --endregion
+
+// --region 预热调度
+
+/**
+ * 确保目标路径的 Monaco model 存在（供 hover 定义预览的 createModelReference 命中）。
+ *
+ * 降级语义：未安装实现（编辑器页签未挂载）、路径为空、处于失败冷却、实现失败或超时，
+ * 一律返回 false 且不抛异常——此时行为等价于修复前（预览不显示，但不再产生未捕获异常）。
+ * @author ddj 2026年10月20号
+ * @param path 工作区相对路径（或绝对路径，由实现决定如何解析）
+ * @returns 预热成功返回 true；被跳过/失败/超时返回 false
+ */
+export function warmModelFor(path: string): Promise<boolean> {
+  if (!path || !impl) return Promise.resolve(false)
+
+  const running = inFlight.get(path)
+  if (running) return withTimeout(path, running)
+  if (isCooling(path)) return Promise.resolve(false)
+
+  return withTimeout(path, startWarm(path, impl))
+}
+// --endregion

package/src/client/styles/editor.css

@@ -16,6 +16,11 @@
 /* 固定页签：📌 标记 + 免关闭按钮（固定页签不渲染 ×，仅可经右键菜单取消固定） */
 [data-edrv-view] .edrv-tab .edrv-tab-pin { flex-shrink: 0; font-size: 10px; line-height: 1; opacity: .85; }
 [data-edrv-view] .edrv-tab.edrv-tab-pinned { background: var(--dsw-alias-bg-layer-2, rgba(255,255,255,.04)); }
+/* 页签行 = 可横滚的页签区 + 行尾固定工具列（计划预览页签与磁盘页签同处这一行的滚动区）@author ddj 2026年10月20号 */
+[data-edrv-view] .edrv-tabs-row { display: flex; align-items: center; min-width: 0; flex: 0 0 auto; background: var(--dsw-alias-bg-layer-1, transparent); }
+/* 特异性需盖过下面 .edrv-group .edrv-tabs 的 flex: 0 0 auto，页签区才能吃掉行走宽、把工具列压到行尾 */
+[data-edrv-view] .edrv-group .edrv-tabs-row > .edrv-tabs { flex: 1 1 auto; min-width: 0; background: transparent; }
+[data-edrv-view] .edrv-tabs-tools { display: flex; align-items: center; gap: 2px; flex: 0 0 auto; padding: 0 6px 0 2px; }
 [data-edrv-view] .edrv-tab-add { display: inline-flex; align-items: center; justify-content: center; width: 24px; height: 24px; margin-left: 2px; border: none; border-radius: 6px; background: transparent; color: var(--dsw-alias-label-secondary, #aaa); font-size: 14px; cursor: pointer; flex-shrink: 0; }
 [data-edrv-view] .edrv-tab-add:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.06)); }
 [data-edrv-view] .edrv-pathbar { display: flex; align-items: center; gap: 8px; height: 26px; padding: 0 10px; background: var(--dsw-alias-bg-layer-1, #ffffff); border-bottom: 1px solid var(--dsw-alias-border-l1, #e0e6e8); font-size: 12px; flex-shrink: 0; overflow: hidden; }
@@ -300,6 +305,14 @@
 [data-edrv-view] .edrv-side-btn { display: inline-flex; align-items: center; justify-content: center; width: 22px; height: 22px; border: none; border-radius: 6px; background: transparent; color: var(--dsw-alias-label-secondary, #52606d); font-size: 12px; cursor: pointer; flex-shrink: 0; }
 [data-edrv-view] .edrv-side-btn:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
 [data-edrv-view] .edrv-tree { flex: 1; min-height: 0; overflow: auto; padding: 4px 6px 12px; font-size: 12px; }
+/* Virtual rows and placeholders share the same geometry as treeWindow.ts. @author ddj 2026年10月22号 */
+[data-edrv-view] .edrv-tree.edrv-tree-virtual { padding-top: 0; padding-bottom: 0; }
+[data-edrv-view] .edrv-tree-virtual .edrv-tree-row,
+[data-edrv-view] .edrv-tree-virtual .edrv-tree-loading { height: 24px; min-height: 24px; box-sizing: border-box; }
+[data-edrv-view] .edrv-tree-virtual .edrv-tree-loading { line-height: 24px; }
+[data-edrv-view] .edrv-large-text { flex: 1; min-width: 0; min-height: 0; display: flex; flex-direction: column; }
+[data-edrv-view] .edrv-large-text-toolbar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+[data-edrv-view] .edrv-large-text-content { margin: 0; flex: 1; min-height: 0; overflow: auto; white-space: pre; font-family: var(--ds-font-family-code, ui-monospace, monospace); user-select: text; }
 [data-edrv-view] .edrv-tree-row { display: flex; align-items: center; gap: 4px; height: 22px; padding-right: 6px; border-radius: 5px; color: var(--dsw-alias-label-primary, #1f2933); cursor: pointer; white-space: nowrap; }
 [data-edrv-view] .edrv-tree-row:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.08)); }
 [data-edrv-view] .edrv-tree-row.edrv-tree-active { background: var(--dsw-alias-interactive-bg-hover, rgba(15,157,88,.14)); }
@@ -988,7 +1001,6 @@
 [data-edrv-view] .edrv-group { border: 0; }
 [data-edrv-view] .edrv-group .edrv-tabs { flex: 0 0 auto; touch-action: none; }
 [data-edrv-view] .edrv-group-tab-name { overflow: hidden; text-overflow: ellipsis; max-width: 180px; }
-[data-edrv-view] .edrv-workbench-tools { flex: 0 0 auto; }
 [data-edrv-view] .edrv-split { display: flex; flex: 1 1 auto; min-width: 0; min-height: 0; overflow: hidden; }
 [data-edrv-view] .edrv-split-vertical { flex-direction: column; }
 [data-edrv-view] .edrv-split-child { display: flex; min-width: 0; min-height: 0; overflow: hidden; }