dsh-vscode-mode 0.14.3 → 0.14.5

package/src/client/monaco/diffRender.ts

@@ -1,190 +1,250 @@
 // @ts-nocheck
-/**
- * dsh-vscode-mode client — 行内差异自绘（新增行绿底 + glyph margin '+'；删除块 view zone 红底）。
- * 迁移自原 src/client/index.ts 的 diff-render effect，语义不改。
- * 作者 ddj 2026-08-20
- */
+/** 行内差异：共享色盘、删除代码高亮与原行号。 @author ddj 2026年10月09号 */
+import { detectColorScheme, officialThemeOf, themeNameOf } from './theme.js'
+
+// #region 显示数据
+/** @private @author ddj 2026年10月09号 @param regions 待显示区域 @returns 内容敏感且无分隔符碰撞的展示键 */
+function renderKey(regions) {
+  return JSON.stringify(regions.map((r) => [r.callId, r.idx, r.start, r.end, r.oldStart, r.create, r.oldLines, r.newLines]))
+}
+
+/** @private @author ddj 2026年10月09号 @param node 接收样式的节点 @param colors Monaco 颜色 @returns 设置插件局部变量；不覆盖官方令牌 */
+function setDiffColors(node, colors) {
+  if (!node) return
+  node.style.setProperty('--edrv-diff-add', colors['diffEditor.insertedLineBackground'])
+  node.style.setProperty('--edrv-diff-del', colors['diffEditor.removedLineBackground'])
+  node.style.setProperty('--edrv-diff-fg', colors['editor.foreground'] || '#1e1e1e')
+  node.style.setProperty('--edrv-diff-number', colors['editorLineNumber.foreground'] || '#6c6c6c')
+}
+
+/** @private @author ddj 2026年10月09号 @param text 源码行 @returns 安全纯文本行；不把源码写入 HTML */
+function codeRow(text) {
+  const row = document.createElement('div')
+  row.className = 'edrv-del-row'
+  const span = document.createElement('span')
+  span.className = 'edrv-del-text'
+  span.textContent = text
+  row.appendChild(span)
+  return row
+}
+
+/** @private @author ddj 2026年10月09号 @param line 原行号（缺失则占位） @returns 旧行号与减号行 */
+function marginRow(line) {
+  const row = document.createElement('div')
+  row.className = 'edrv-del-margin-row'
+  const number = document.createElement('span')
+  number.className = 'edrv-del-number'
+  number.textContent = line === undefined ? '·' : String(line)
+  if (line === undefined) number.title = '历史记录缺少可验证的原行号'
+  const marker = document.createElement('span')
+  marker.className = 'edrv-del-marker'
+  marker.textContent = '−'
+  row.appendChild(number)
+  row.appendChild(marker)
+  return row
+}
+
+/** @private @author ddj 2026年10月09号 @param region 差异区域 @returns 正文与边栏节点；Monaco 管理两者滚动 */
+function zoneOf(region) {
+  const domNode = document.createElement('div')
+  domNode.className = 'edrv-del-zone'
+  domNode.dataset.edrvHunk = String(region.callId) + ':' + region.idx
+  const marginDomNode = document.createElement('div')
+  marginDomNode.className = 'edrv-del-margin'
+  const rows = []
+  for (let index = 0; index < region.oldLines.length; index++) {
+    const row = codeRow(region.oldLines[index])
+    domNode.appendChild(row)
+    rows.push(row.firstChild)
+    marginDomNode.appendChild(marginRow(region.oldStart === undefined ? undefined : region.oldStart + index))
+  }
+  return { domNode, marginDomNode, rows, lines: region.oldLines, after: Math.max(0, region.start - 1) }
+}
+// #endregion
 
 /**
- * 差异渲染器（每 EditorView 挂载一个，内部持有 zone/decoration 状态）。
- * @param log 诊断日志函数（(sessionId, text) => void）
+ * 每个编辑器视图一个渲染器；持有并释放装饰、区域与监听。
+ * @public @author ddj 2026年10月09号
+ * @param log 诊断日志函数（失败不影响展示）
+ * @returns render、refresh 与 dispose；不修改审查决策或编辑器模型
  */
 export function createDiffRenderer(log) {
-  let viewZoneIds = []
+  let owner = null
+  let api = null
+  let model = null
+  let language = null
+  let session = null
+  let pending = []
+  let zones = []
   let decorations = []
-  /** 上次已渲染的差异指纹（callId:idx@start-end:oldLen/newLen 串）：内容未变时跳过重建。 */
+  let listeners = []
   let lastKey = null
+  let generation = 0
+  let theme = themeNameOf()
 
-  /**
-   * 渲染当前 pending 差异：绿底 decoration + 删除块 view zones + '-' 号 overlay（滚动同步）。
-   * @param monaco window.monaco
-   * @param editor Monaco 编辑器实例
-   * @param pendingRegions 待处理差异区域
-   * @param sessionId 会话 id
-   */
-  const render = (monaco, editor, pendingRegions, sessionId) => {
-    // 空渲染且无残留（5s 轮询 setRecords 常触发）：无需清理时直接跳过，
-    // 不打 begin 日志、不做无谓 DOM 操作；有 zone/decoration 残留时仍需走清理。
-    if (!pendingRegions.length && viewZoneIds.length === 0 && decorations.length === 0) return
-    const renderT0 = Date.now()
-    const callIdAttr = (callId, idx) => String(callId) + ':' + String(idx)
-    // 指纹相同 = 内容未变（轮询/引用空转/重复点击触发的重渲染）：残留 DOM 已在位，
-    // 直接跳过整轮重建（view zones 拆建 / overlay DOM / 50ms 校正），消除同区域重复渲染成本。
-    const key = pendingRegions.map((r) => callIdAttr(r.callId, r.idx) + '@' + (r.start ?? '?') + '-' + (r.end ?? '?') + ':' + (r.oldLines ? r.oldLines.length : 0) + '/' + (r.newLines ? r.newLines.length : 0)).join('|')
-    if (key === lastKey) return
-    lastKey = key
-    log(sessionId, '[diff-render] begin regs=' + pendingRegions.length + ' ' + pendingRegions.map((r) => callIdAttr(r.callId, r.idx) + '@' + (r.start ?? '?') + '-' + (r.end ?? '?') + '(-' + (r.oldLines ? r.oldLines.length : 0) + '/+' + (r.newLines ? r.newLines.length : 0) + ')').join('|'))
-
-    const decos = []
-    for (const r of pendingRegions) {
-      if (r.start === undefined || r.end === undefined) continue
-      if (r.newLines && r.newLines.length) {
-        decos.push({
-          range: new monaco.Range(r.start, 1, Math.max(r.start, r.end - 1), 1),
-          options: { isWholeLine: true, className: 'edrv-mn-add-line', linesDecorationsClassName: 'edrv-mn-gutter-add' },
-        })
+  // #region 生命周期
+  /** @private @author ddj 2026年10月09号 清除区域与异步代次；保留编辑器和监听以便刷新。 */
+  function clear() {
+    generation++
+    lastKey = null
+    if (owner) {
+      try { decorations = owner.deltaDecorations(decorations, []) } catch { decorations = [] }
+      /** @author ddj 2026年10月09号 @param accessor Monaco 区域事务 */
+      function removeZones(accessor) {
+        for (const zone of zones) accessor.removeZone(zone.id)
       }
+      try { owner.changeViewZones(removeZones) } catch { /* 编辑器可能已销毁。 */ }
     }
-    decorations = editor.deltaDecorations(decorations, decos)
-
-    // 删除块 view zones（红底 + 正文；- 号由独立 overlay 层渲染，定位在 decoration 列与 + 同列，
-    // 不受 view zone 容器定位/裁剪影响；滚动用 translateY 同步）
-    let createdZones = []
-    editor.changeViewZones((accessor) => {
-      for (const id of viewZoneIds) { try { accessor.removeZone(id) } catch (e) { /* 已移除 */ } }
-      viewZoneIds = []
-      const zones = []
-      for (const r of pendingRegions) {
-        if (r.create) continue
-        const oldLines = r.oldLines && r.oldLines.length ? r.oldLines : null
-        if (!oldLines) continue
-        const after = Math.max(0, (r.start ?? 1) - 1)
-        const domNode = document.createElement('div')
-        domNode.className = 'edrv-del-zone'
-        domNode.dataset.edrvHunk = callIdAttr(r.callId, r.idx)
-        for (const t of oldLines) {
-          const row = document.createElement('div')
-          row.className = 'edrv-del-row'
-          const text = document.createElement('span')
-          text.className = 'edrv-del-text'
-          text.textContent = t
-          row.appendChild(text)
-          domNode.appendChild(row)
-        }
-        const id = accessor.addZone({
-          afterLineNumber: after,
-          heightInLines: oldLines.length,
-          domNode,
-          suppressMouseDown: false,
-        })
-        viewZoneIds.push(id)
-        zones.push({ domNode, after, n: oldLines.length })
-      }
-      createdZones = zones
-    })
-
-    if (createdZones.length) {
-      const root = editor.getDomNode()
-      if (root) {
-        let overlay = root.querySelector('.edrv-minus-overlay')
-        if (!overlay) {
-          overlay = document.createElement('div')
-          overlay.className = 'edrv-minus-overlay'
-          root.appendChild(overlay)
-        }
-        overlay.innerHTML = ''
-        const lineH = editor.getOption(monaco.editor.EditorOption.lineHeight) || 20
-        let li = null
-        try { li = editor.getLayoutInfo() } catch (e) { /* ignore */ }
-        const rawLeft = li ? li.decorationsLeft : 0
-        const width = li && li.decorationsWidth > 0 ? li.decorationsWidth : 16
-        // decorationsLeft 是 Monaco 内部坐标，需限制在宿主根节点内，避免窄窗口/边框
-        // 或布局尚未完成时把减号绘制到编辑器左、右边界之外。
-        const maxLeft = Math.max(0, root.clientWidth - width)
-        // 字符本身有少量字体侧向留白；给标记列留出 4px 内缩，避免减号半个
-        // 字符落到 Monaco 根节点左边框外，同时仍限制右侧不越界。
-        const markerInset = 12
-        const left = Math.max(0, Math.min(maxLeft, rawLeft + markerInset))
-        const lineCount = editor.getModel().getLineCount()
-        let itemIdx = 0
-        let zi = 0
-        for (const z of createdZones) {
-          // 用 Monaco 坐标 API 计算 view zone 顶部，避免离屏 zone DOM 未布局导致 getBoundingClientRect 为 0
-          const anchor = Math.min(z.after + 1, lineCount)
-          let zoneBottom = editor.getTopForLineNumber(anchor)
-          if (z.after >= lineCount) zoneBottom += lineH
-          const zoneTop = zoneBottom - z.n * lineH
-          for (let i = 0; i < z.n; i++) {
-            const item = document.createElement('div')
-            item.className = 'edrv-minus-item'
-            // 使用 CSS 线段代替文本字符，避免不同字体的侧向留白把 “-” 绘制到边界外。
-            item.textContent = ''
-            item.style.width = width + 'px'
-            item.style.height = lineH + 'px'
-            item.dataset.zone = String(zi)
-            item.dataset.row = String(i)
-            item.style.top = (zoneTop + i * lineH) + 'px'
-            item.style.left = left + 'px'
-            overlay.appendChild(item)
-            itemIdx++
-          }
-          zi++
-        }
-        log(sessionId, '[diff-render] placed zones=' + createdZones.length + ' items=' + itemIdx + ' left=' + left + ' w=' + width + ' t+' + (Date.now() - renderT0) + 'ms')
-        // 滚动同步：overlay 随内容滚动（内容坐标 - scrollTop）
-        const syncScroll = () => {
-          const s2 = editor.getScrollTop() || 0
-          if (overlay) overlay.style.transform = 'translateY(' + (-s2) + 'px)'
-        }
-        syncScroll()
-        overlay.__edrvSync = syncScroll
-        if (!overlay.__edrvBound) {
-          overlay.__edrvBound = true
-          editor.onDidScrollChange(syncScroll)
-        }
-        // 已可见的 zone 用真实 DOM 坐标做一次微调（离屏 zone 仍保留坐标 API 位置）
-        setTimeout(() => {
-          try {
-            const edRect = root.getBoundingClientRect()
-            const st = editor.getScrollTop() || 0
-            const items = overlay.querySelectorAll('.edrv-minus-item')
-            let correctedLeft = left
-            try {
-              const layout = editor.getLayoutInfo()
-              const markerWidth = layout.decorationsWidth > 0 ? layout.decorationsWidth : width
-              correctedLeft = Math.max(0, Math.min(Math.max(0, root.clientWidth - markerWidth), (layout.decorationsLeft || 0) + 12))
-            } catch (e) { /* 保留首次布局计算结果 */ }
-            for (const item of items) {
-              item.style.left = correctedLeft + 'px'
-              const zIndex = Number(item.dataset.zone)
-              const rIndex = Number(item.dataset.row)
-              const z = createdZones[zIndex]
-              if (!z || !z.domNode.isConnected) continue
-              const rowEl = z.domNode.querySelectorAll('.edrv-del-row')[rIndex]
-              if (!rowEl) continue
-              const rowRect = rowEl.getBoundingClientRect()
-              if (rowRect.height > 0) {
-                item.style.top = (rowRect.top - edRect.top + st) + 'px'
-              }
-            }
-          } catch (e) { log(sessionId, '[diff-render] correct fail ' + String(e)) }
-        }, 50)
-      }
-    } else {
-      const root = editor.getDomNode()
-      const overlay = root && root.querySelector('.edrv-minus-overlay')
-      if (overlay) overlay.innerHTML = ''
+    zones = []
+  }
+
+  /** @public @author ddj 2026年10月09号 释放所有本渲染器拥有的资源；允许之后重新绑定。 */
+  function dispose() {
+    for (const listener of listeners) listener.dispose()
+    listeners = []
+    clear()
+    owner = model = api = null
+    pending = []
+  }
+
+  /** @private @author ddj 2026年10月09号 模型切换时丢弃旧区域，等待 React 提供新模型的区域。 */
+  function modelChanged() {
+    clear()
+    model = owner.getModel()
+    pending = []
+  }
+
+  /** @private @author ddj 2026年10月09号 @param monaco Monaco API @param editor 编辑器；只订阅一次 */
+  function bind(monaco, editor) {
+    if (owner === editor) return
+    dispose()
+    owner = editor
+    api = monaco
+    for (const event of ['onDidChangeConfiguration', 'onDidChangeModelLanguage', 'onDidChangeModelOptions']) {
+      if (typeof owner[event] === 'function') listeners.push(owner[event](refresh))
     }
-    // #region debug log
-    try { log(sessionId, '[DEBUG diffRender] regions=' + pendingRegions.length + ' zones=' + createdZones.length + ' ms=' + (Date.now() - renderT0)) } catch (e) { /* 诊断不可影响渲染 */ }
-    // #endregion
+    if (owner.onDidLayoutChange) listeners.push(owner.onDidLayoutChange(reflow))
+    if (owner.onDidChangeModel) listeners.push(owner.onDidChangeModel(modelChanged))
+    if (owner.onDidDispose) listeners.push(owner.onDidDispose(dispose))
+  }
+  // #endregion
+
+  // #region 着色与布局
+  /** @private @author ddj 2026年10月09号 @param zone 删除区域 @param epoch 发起代次；拒绝旧模型、语言和主题结果 */
+  async function colorZone(zone, epoch) {
+    if (typeof api.editor.colorize !== 'function') return
+    const sourceModel = model
+    const sourceLang = language
+    const sourceTheme = theme
+    const tabSize = sourceModel.getOptions?.().tabSize || 4
+    try {
+      const html = await api.editor.colorize(zone.lines.join('\n'), sourceLang, { tabSize })
+      if (epoch !== generation || owner?.getModel() !== sourceModel || sourceModel.getLanguageId() !== sourceLang || theme !== sourceTheme) return
+      // Monaco 生成的 HTML 已转义源码；逐行分配仅使用其输出，不拼接用户源码。
+      const lines = html.split(/<br\s*\/?\s*>/i)
+      if (lines.length === zone.rows.length + 1 && lines.at(-1) === '') lines.pop()
+      if (lines.length !== zone.rows.length) return
+      for (let index = 0; index < lines.length; index++) zone.rows[index].innerHTML = lines[index]
+    } catch { /* 保留立即显示的安全纯文本。 */ }
   }
 
-  /** 卸载清理（EditorView unmount 时调用）。 */
-  const dispose = () => {
-    viewZoneIds = []
-    decorations = []
+  /** @private @author ddj 2026年10月09号 @param zone 区域 @param colors 当前主题颜色；跟随 Monaco 实际字体/布局 */
+  function layoutZone(zone, colors) {
+    const layout = owner.getLayoutInfo()
+    const font = owner.getOption(api.editor.EditorOption.fontInfo)
+    const lineHeight = owner.getOption(api.editor.EditorOption.lineHeight) || 20
+    const tabSize = model.getOptions?.().tabSize || 4
+    owner.applyFontInfo?.(zone.domNode)
+    owner.applyFontInfo?.(zone.marginDomNode)
+    setDiffColors(zone.domNode, colors)
+    setDiffColors(zone.marginDomNode, colors)
+    zone.domNode.style.setProperty('--edrv-line-height', lineHeight + 'px')
+    zone.domNode.style.tabSize = String(tabSize)
+    zone.marginDomNode.style.setProperty('--edrv-line-height', lineHeight + 'px')
+    zone.marginDomNode.style.setProperty('--edrv-number-left', layout.lineNumbersLeft + 'px')
+    zone.marginDomNode.style.setProperty('--edrv-number-width', layout.lineNumbersWidth + 'px')
+    zone.marginDomNode.style.setProperty('--edrv-marker-left', layout.decorationsLeft + 'px')
+    zone.marginDomNode.style.setProperty('--edrv-marker-width', layout.decorationsWidth + 'px')
+    let width = 0
+    for (const line of zone.lines) width = Math.max(width, line.replace(/\t/g, ' '.repeat(tabSize)).length)
+    // 中文/宽字符不能按半宽估算；宁可保留余量，也不截断旧代码横向滚动范围。
+    const charWidth = Math.max(font?.typicalHalfwidthCharacterWidth || 8, font?.typicalFullwidthCharacterWidth || 0)
+    return width * charWidth + 24
+  }
+
+  /** @private @author ddj 2026年10月09号 容器大小变化只更新边栏几何，不重新着色/重建区域。 */
+  function reflow() {
+    if (!owner || !model) return
+    const colors = officialThemeOf(detectColorScheme()).colors
+    for (const zone of zones) layoutZone(zone, colors)
+  }
+
+  /** @private @author ddj 2026年10月09号 @param accessor Monaco 区域事务 @param colors 共享色盘 */
+  function addZones(accessor, colors) {
+    for (const region of pending) {
+      if (region.create || region.start === undefined || !region.oldLines?.length) continue
+      const zone = zoneOf(region)
+      const minWidthInPx = layoutZone(zone, colors)
+      zone.id = accessor.addZone({
+        afterLineNumber: zone.after, heightInLines: zone.lines.length,
+        domNode: zone.domNode, marginDomNode: zone.marginDomNode,
+        minWidthInPx, suppressMouseDown: false,
+      })
+      zones.push(zone)
+      void colorZone(zone, generation)
+    }
   }
 
-  return { render, dispose }
+  /** @private @author ddj 2026年10月09号 @returns 新增行整行背景和加号装饰 */
+  function addDecorations() {
+    const out = []
+    for (const region of pending) {
+      if (region.start === undefined || region.end === undefined || !region.newLines?.length) continue
+      out.push({
+        range: new api.Range(region.start, 1, Math.max(region.start, region.end - 1), 1),
+        options: { isWholeLine: true, className: 'edrv-mn-add-line', marginClassName: 'edrv-mn-add-line', linesDecorationsClassName: 'edrv-mn-gutter-add' },
+      })
+    }
+    return out
+  }
+  // #endregion
+
+  // #region 渲染入口
+  /** @private @author ddj 2026年10月09号 按内容/模型/语言展示；空区域也能清除残留。 */
+  function paint() {
+    if (!owner) return
+    const nextModel = owner.getModel()
+    if (!nextModel) { clear(); return }
+    const nextLang = nextModel.getLanguageId()
+    const key = renderKey(pending)
+    if (lastKey === key && model === nextModel && language === nextLang) return
+    clear()
+    model = nextModel
+    language = nextLang
+    lastKey = key
+    const colors = officialThemeOf(detectColorScheme()).colors
+    setDiffColors(owner.getDomNode(), colors)
+    decorations = owner.deltaDecorations([], addDecorations())
+    /** @author ddj 2026年10月09号 @param accessor Monaco 区域事务 */
+    function mountZones(accessor) { addZones(accessor, colors) }
+    owner.changeViewZones(mountZones)
+    try { log?.(session, '[diff-render] regions=' + pending.length + ' zones=' + zones.length) } catch { /* 诊断不可影响渲染。 */ }
+  }
+
+  /** @public @author ddj 2026年10月09号 @param themeId 新应用的主题名（事件参数不作为主题名） 更新字体、语言或主题后重新着色。 */
+  function refresh(themeId) {
+    if (typeof themeId === 'string') theme = themeId
+    lastKey = null
+    paint()
+  }
+
+  /** @public @author ddj 2026年10月09号 @param monaco Monaco API @param editor 编辑器 @param regions 待显示区域 @param sessionId 会话 id */
+  function render(monaco, editor, regions, sessionId) {
+    bind(monaco, editor)
+    pending = regions
+    session = sessionId
+    paint()
+  }
+  // #endregion
+  return { render, refresh, dispose }
 }

package/src/client/monaco/theme.ts

@@ -118,6 +118,30 @@ const LIGHT_RULES = [
   { token: 'invalid', foreground: 'cd3131' },
 ]
 
+/** 截图对齐回落色盘；未取得官方差异令牌，不宣称这些值为官方精确色值。 */
+const DIFF_PALETTE = {
+  light: ['#e6f4e8', '#fbe7e3', '#b7e3bf80', '#f1b1a780'],
+  dark: ['#203b2c', '#482b2b', '#2d684880', '#8c454580'],
+}
+
+/**
+ * 行内与 Monaco 差异视图共享色盘，避免通用 hover 令牌覆盖增删语义。
+ * @public @author ddj 2026年10月09号
+ * @param scheme 明暗主题
+ * @returns Monaco 差异颜色键；调用方可安全修改返回对象
+ */
+export function diffColorsOf(scheme) {
+  const [added, removed, addText, delText] = DIFF_PALETTE[scheme === 'light' ? 'light' : 'dark']
+  return {
+    'diffEditor.insertedLineBackground': added,
+    'diffEditor.removedLineBackground': removed,
+    'diffEditor.insertedTextBackground': addText,
+    'diffEditor.removedTextBackground': delText,
+    'diffEditorGutter.insertedLineBackground': added,
+    'diffEditorGutter.removedLineBackground': removed,
+  }
+}
+
 /** 编辑器 UI 配色（与语法配色同套，保证 gutter/minimap/selection 一致）。 */
 const DARK_COLORS = {
   'editor.background': '#1e1e1e',
@@ -137,14 +161,7 @@ const DARK_COLORS = {
   'scrollbarSlider.background': '#79797966',
   'scrollbarSlider.hoverBackground': '#646464b3',
   'scrollbarSlider.activeBackground': '#bfbfbf66',
-  // 差异视图色块（本仓库 vendored Monaco 无 .line-insert 静态背景规则，靠主题键保证；
-  // 色相取自研差异 UI 同源：绿 #0f9d58 / 红 #d9534f，alpha 提到肉眼可辨）
-  'diffEditor.insertedLineBackground': '#0f9d5830',
-  'diffEditor.removedLineBackground': '#d9534f2e',
-  'diffEditor.insertedTextBackground': '#0f9d5833',
-  'diffEditor.removedTextBackground': '#d9534f40',
-  'diffEditorGutter.insertedLineBackground': '#0f9d5859',
-  'diffEditorGutter.removedLineBackground': '#d9534f59',
+  ...diffColorsOf('dark'),
 }
 
 const LIGHT_COLORS = {
@@ -165,13 +182,7 @@ const LIGHT_COLORS = {
   'scrollbarSlider.background': '#64646466',
   'scrollbarSlider.hoverBackground': '#646464b3',
   'scrollbarSlider.activeBackground': '#00000099',
-  // 差异视图色块（同上：主题键保证整行背景可见；色相/透明度与暗色一致）
-  'diffEditor.insertedLineBackground': '#0f9d5830',
-  'diffEditor.removedLineBackground': '#d9534f2e',
-  'diffEditor.insertedTextBackground': '#0f9d5833',
-  'diffEditor.removedTextBackground': '#d9534f40',
-  'diffEditorGutter.insertedLineBackground': '#0f9d5859',
-  'diffEditorGutter.removedLineBackground': '#d9534f59',
+  ...diffColorsOf('light'),
 }
 
 /**

package/src/client/officialSidebar.ts

@@ -60,6 +60,8 @@ export function deferToOfficial(path: unknown): boolean {
 export interface OfficialTabParams {
   openPath?: string
   focusDiff?: boolean
+  /** Open Markdown in rendered mode; explicit line navigation still selects source. */
+  preview?: boolean
   /** 目标行号（行引用/工具行跳转透传；缺省仅打开文件）。 */
   line?: number
 }
@@ -72,7 +74,7 @@ export interface SidebarRightTabsLike {
 /** sidebarRight 服务的最小结构面（openTab 页路由 + openResource 资源路由 + 可选查询/定向打开）。 */
 export interface SidebarRightServiceLike {
   openTab: (kind: string, options?: { params?: unknown }) => void
-  openResource?: (address: string, options?: { params?: unknown }) => void
+  openResource?: (address: string, options?: { params?: unknown; kind?: string }) => void
   /** 挂载会话的激活 Tab（判读编辑 Tab 是否已激活；无 seat 时 undefined）。 */
   active?: () => { kind?: string } | undefined
   /** 向指定会话的停靠面打开页类型（store 未 adopt 时 no-op）。 */
@@ -226,16 +228,19 @@ export function buildFileAddress(path: string, sessionId?: string): string {
  * @param service 官方 sidebarRight 服务（缺失/缺 openTab 返回 false）
  * @param path 目标文件路径（空值返回 false）
  * @param line 可选行号（透传给编辑器页签导航参数）
+ * @param preview 可选 Markdown 渲染模式（行号导航优先源码）
  * @returns 转发是否成功（openTab 抛错返回 false，由调用方决定重试或兜底）
  */
 export function forwardToEditor(
   service: SidebarRightServiceLike | undefined | null,
   path: string | null,
   line?: number,
+  preview?: boolean,
 ): boolean {
   if (!service || typeof service.openTab !== 'function' || !path) return false
   const params: OfficialTabParams = { openPath: path }
   if (line !== undefined) params.line = line
+  if (preview !== undefined) params.preview = preview
   try {
     // 官方语义：页类型恒去重，故转发只会聚焦既有编辑器页签，不产生新实例
     service.openTab(OFFICIAL_TAB_KIND, { params })

package/src/client/openReceipt.ts

@@ -1,6 +1,9 @@
 import { openEditorView } from './events.js'
 
-export interface EditorRequest { requestId: string; sessionId: string; path: string | null; line?: number; column?: number }
+import type { PlanDocument } from './planState.js'
+
+export interface EditorRequest { requestId: string; sessionId: string; path: string | null; line?: number; column?: number; preview?: boolean; plan?: PlanDocument }
+export interface OpenOptions { preview?: boolean; plan?: PlanDocument; signal?: AbortSignal }
 interface Waiter { request: EditorRequest; finish: (success: boolean) => void; claimed?: boolean }
 const waiters = new Map<string, Waiter>()
 
@@ -33,19 +36,26 @@ export function finishOpen(requestId: string, success: boolean, error?: string):
  * @param line Optional target line.
  * @param column Optional target column.
  * @param sessionId Owning session, required for routing.
+ * @param options Explicit preview, read-only plan document and optional cancellation signal.
  * @returns Actual completion; timeout and disposal are false.
  */
-export function requestOpen(path: string | null, line?: number, column?: number, sessionId = ''): Promise<boolean> {
-  if (typeof window === 'undefined' || !sessionId) return Promise.resolve(false)
+export function requestOpen(path: string | null, line?: number, column?: number, sessionId = '', options: OpenOptions = {}): Promise<boolean> {
+  if (typeof window === 'undefined' || !sessionId || options.signal?.aborted) return Promise.resolve(false)
   const request: EditorRequest = { requestId: crypto.randomUUID(), sessionId, path, line, column }
+  if (options.preview !== undefined) request.preview = options.preview
+  if (options.plan) request.plan = options.plan
   return new Promise((resolve) => {
     let timer: ReturnType<typeof setTimeout>
     /** @private @author ddj 2026年09月28号 Complete once and release the deadline. */
     function finish(success: boolean): void {
       clearTimeout(timer)
+      options.signal?.removeEventListener('abort', abort)
       waiters.delete(request.requestId)
       resolve(success)
     }
+    /** @private @author ddj 2026年10月08号 Cancel a stale plan open on scope change or disposal. */
+    function abort(): void { finish(false) }
+    options.signal?.addEventListener('abort', abort, { once: true })
     waiters.set(request.requestId, { request, finish })
     timer = setTimeout(() => finish(false), 20_000)
     openEditorView(null)