dsh-vscode-mode 0.5.3 → 0.6.0

package/src/client/dap/decorate.ts

@@ -0,0 +1,128 @@
+/**
+ * dsh-vscode-mode client — Monaco 调试装饰：断点圆点（gutter）与停帧行高亮。
+ * 装饰 id 挂在 editor 实例属性上（与 diffRender/underline/navFlash 同款隔离模式），
+ * 独立 collection 互不干扰；range 用 IRange 形状普通对象（Monaco 内部归一化，
+ * 与 navFlashRangeOf 产物同口径）；编辑器销毁时装饰随实例消失，无需显式清理。
+ * 作者 ddj 2026年09月29号
+ */
+
+/** editor 上的装饰 id 槽位 key。 */
+const BP_KEY = '__edrvDapBpDecorations'
+const PAUSED_KEY = '__edrvDapPausedDecorations'
+const EDITING_KEY = '__edrvDapEditingDecorations'
+const HINT_KEY = '__edrvDapHintDecorations'
+/** 当前 hover 预览行（避免同一行重复设置装饰）。 */
+const HINT_LINE = '__edrvDapHintLine'
+
+/** Monaco editor 最小子集（deltaDecorations 旧 API，工程内既有口径）。 */
+interface DecoEditor {
+  deltaDecorations(oldIds: string[], next: unknown[]): string[]
+}
+
+/** IRange 形状普通对象。 */
+function lineRange(line: number): unknown {
+  return { startLineNumber: line, startColumn: 1, endLineNumber: line, endColumn: 1 }
+}
+
+/**
+ * 应用断点装饰（全量替换：启用行红点 + 未验证行空心红圈 + 禁用行灰点）。
+ * 未验证 = 适配器真实回执 verified:false（如该行无可执行代码），对齐 VS Code 空心圆语义。
+ * @author ddj 2026年09月29号 / 2026年09月21号
+ * @param editor Monaco 编辑器
+ * @param enabledLines 启用断点行
+ * @param disabledLines 禁用断点行
+ * @param unverifiedLines 启用但未验证的行（缺省视为全部已验证）
+ */
+export function applyBpDecorations(editor: unknown, enabledLines: number[], disabledLines: number[], unverifiedLines: readonly number[] = []): void {
+  const ed = editor as DecoEditor | null
+  if (!ed?.deltaDecorations) return
+  const make = (line: number, cls: string) => ({
+    range: lineRange(line),
+    options: { isWholeLine: true, glyphMarginClassName: cls, glyphMarginHoverMessage: { value: '断点（点击行首圆点处切换）' } },
+  })
+  const next = [
+    ...enabledLines.map((line) => make(line, unverifiedLines.includes(line) ? 'edrv-dap-bp-unverified' : 'edrv-dap-bp')),
+    ...disabledLines.map((line) => make(line, 'edrv-dap-bp-off')),
+  ]
+  const slot = ed as unknown as Record<string, unknown>
+  const prev = slot[BP_KEY] as string[] | undefined
+  slot[BP_KEY] = ed.deltaDecorations(prev ?? [], next)
+}
+
+/**
+ * 设置停帧行装饰（null/0 清除；整行浅底 + gutter 箭头）。
+ * @author ddj 2026年09月29号
+ * @param editor Monaco 编辑器
+ * @param line 停帧行
+ */
+export function setPausedLine(editor: unknown, line: number | null): void {
+  const ed = editor as DecoEditor | null
+  if (!ed?.deltaDecorations) return
+  const slot = ed as unknown as Record<string, unknown>
+  const prev = slot[PAUSED_KEY] as string[] | undefined
+  if (!line) {
+    if (prev?.length) ed.deltaDecorations(prev, [])
+    slot[PAUSED_KEY] = []
+    return
+  }
+  slot[PAUSED_KEY] = ed.deltaDecorations(prev ?? [], [{
+    range: lineRange(line),
+    options: {
+      isWholeLine: true,
+      className: 'edrv-dap-paused-line',
+      glyphMarginClassName: 'edrv-dap-paused-glyph',
+    },
+  }])
+}
+
+/**
+ * 设置「断点编辑中」目标行高亮（打开行内浮层期间；null 清除）。
+ * 对齐 VS Code：编辑断点时目标行整行高亮，明确正在编辑哪一行。
+ * @author ddj 2026年09月29号
+ * @param editor Monaco 编辑器
+ * @param line 目标行（null 清除）
+ */
+export function setEditingLine(editor: unknown, line: number | null): void {
+  const ed = editor as DecoEditor | null
+  if (!ed?.deltaDecorations) return
+  const slot = ed as unknown as Record<string, unknown>
+  const prev = slot[EDITING_KEY] as string[] | undefined
+  if (!line) {
+    if (prev?.length) ed.deltaDecorations(prev, [])
+    slot[EDITING_KEY] = []
+    return
+  }
+  slot[EDITING_KEY] = ed.deltaDecorations(prev ?? [], [{
+    range: lineRange(line),
+    options: { isWholeLine: true, className: 'edrv-dap-editing-line' },
+  }])
+}
+
+/**
+ * 设置 glyph 区 hover 预览断点（半透明小红点；null 清除）。
+ * 对齐 VS Code：鼠标悬停在可下断点的行首区域时，显示低透明度断点预览 + pointer 光标
+ * （其 `.codicon-debug-hint { cursor: pointer; opacity: .4 }` 同源语义）。
+ * 同一行重复调用直接返回（onMouseMove 高频，避免无谓装饰抖动）。
+ * @author ddj 2026年09月29号
+ * @param editor Monaco 编辑器
+ * @param line 预览行（null/0 清除）
+ */
+export function setHintLine(editor: unknown, line: number | null): void {
+  const ed = editor as DecoEditor | null
+  if (!ed?.deltaDecorations) return
+  const slot = ed as unknown as Record<string, unknown>
+  const current = (slot[HINT_LINE] as number | undefined) ?? 0
+  const next = line ?? 0
+  if (current === next) return
+  slot[HINT_LINE] = next
+  const prev = slot[HINT_KEY] as string[] | undefined
+  if (!next) {
+    if (prev?.length) ed.deltaDecorations(prev, [])
+    slot[HINT_KEY] = []
+    return
+  }
+  slot[HINT_KEY] = ed.deltaDecorations(prev ?? [], [{
+    range: lineRange(next),
+    options: { isWholeLine: true, glyphMarginClassName: 'edrv-dap-bp-hint' },
+  }])
+}

package/src/client/dap/hintLine.ts

@@ -0,0 +1,29 @@
+/**
+ * dsh-vscode-mode client — 断点 hover 预览判定（纯函数，可单测）。
+ * 对齐 VS Code `breakpointEditorContribution` 的 onMouseMove 分支：
+ *   `(target.type === GUTTER_GLYPH_MARGIN || target.type === GUTTER_LINE_NUMBERS) &&
+ *    canSetBreakpointsIn(model) && marginFreeFromNonDebugDecorations(line)` → 显示 hint。
+ * 本插件口径：glyph 区（type=2）与行号区（type=3）且该行**尚无断点**时给出预览。
+ * 作者 ddj 2026年09月29号
+ */
+
+/** Monaco MouseTargetType 相关值（实测 0.42-dev：GUTTER_GLYPH_MARGIN=2 / GUTTER_LINE_NUMBERS=3）。 */
+export const TARGET_GUTTER_GLYPH = 2
+export const TARGET_GUTTER_LINE = 3
+
+/**
+ * 判定 hover 是否应显示断点预览，返回预览行号（0 = 不显示）。
+ * @author ddj 2026年09月29号
+ * @param targetType Monaco 鼠标目标类型
+ * @param line 目标行号（0/undefined = 无）
+ * @param existingLines 当前文件已有断点的行号集合
+ * @returns 预览行号；0 表示不显示
+ */
+export function hintLineFor(targetType: number | undefined, line: number | undefined, existingLines: readonly number[]): number {
+  if (targetType !== TARGET_GUTTER_GLYPH && targetType !== TARGET_GUTTER_LINE) return 0
+  const target = Math.floor(Number(line) || 0)
+  if (target < 1) return 0
+  // 已有断点的行不显示预览（避免与实心红点重叠）
+  if (existingLines.includes(target)) return 0
+  return target
+}

package/src/client/dap/hover.ts

@@ -0,0 +1,166 @@
+/**
+ * dsh-vscode-mode client — 暂停态 Lua DAP hover。
+ * provider 只在 DAP paused 时工作，按当前 selectedFrameId 求值，并把「表达式值 + 类型 + 可折叠
+ * 变量树」渲染成**单个 HTML 块**（`[data-edrv-dap]`）；Alt 切换 LSP 信息由 hover 层做行级显隐
+ * （见 hoverTree.ts），因此这里不按 Alt 改变内容，避免依赖 Monaco 的 hover 重算路径。
+ * 作者 ddj 2026年09月29号 / 2026年09月21号
+ */
+import { dapStore } from './store.js'
+import { pathOfModel } from '../monaco/lsp/lspClient.js'
+import { BLOCK_ATTR, EQ_ATTR, EXPR_ATTR, HEAD_ATTR, TYPE_ATTR, VAL_ATTR, createTreeState, escapeHtml, initialHtml } from './hoverTree.js'
+
+const GLOBAL_KEY = '__edrvDapHoverProvider__'
+
+/** Monaco hover 依赖的最小模型接口。 */
+interface HoverModel {
+  getWordAtPosition: (position: HoverPosition) => { word?: string; startColumn: number; endColumn: number } | null
+  getLineContent?: (line: number) => string
+  getLanguageId?: () => string
+}
+
+/** 光标位置（1-based）。 */
+interface HoverPosition {
+  lineNumber: number
+  column: number
+}
+
+/**
+ * 树状态键：表达式 + 模型路径 + 光标范围（同一次 hover 内复用展开状态与缓存）。
+ * @author ddj 2026年09月21号
+ * @param target 光标处表达式与范围
+ * @param path 模型工作区路径
+ * @returns 状态键
+ */
+function treeKeyOf(target: { expression: string; lineNumber: number; startColumn: number; endColumn: number }, path: string): string {
+  return target.expression + '@' + path + ':' + target.lineNumber + ':' + target.startColumn + '-' + target.endColumn
+}
+
+/** Lua 保留字集合（保留字不是可求值表达式，避免 adapter 返回 syntax err 噪声）。 */
+const LUA_KEYWORDS = new Set([
+  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function', 'goto',
+  'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return', 'then', 'true', 'until', 'while',
+])
+
+/** 可求值路径表达式：标识符链，成员用 . 或 : 连接（注释里的中文文本等一律不匹配）。 */
+const EVAL_EXPR = /^[A-Za-z_][A-Za-z0-9_]*(?:[.:][A-Za-z_][A-Za-z0-9_]*)*$/
+
+/**
+ * 是否可交给调试器求值：标识符链且非保留字。
+ * @author ddj 2026年09月21号
+ * @param text 候选表达式
+ * @returns 是否可求值
+ */
+function isEvalExpr(text: string): boolean {
+  return EVAL_EXPR.test(text) && !LUA_KEYWORDS.has(text)
+}
+
+/**
+ * 从光标处提取 Lua 标识符/成员表达式（如 this.model、self:GetName）。
+ * 光标在链首段时只取该段（悬停 this 求 this，而不是 this.canUpdate）；
+ * 光标在成员段时取整条链（悬停 canUpdate 求 this.canUpdate）。
+ * @author ddj 2026年09月29号 / 2026年09月21号
+ * @param model Monaco 文本模型
+ * @param position 光标位置
+ */
+export function expressionAt(model: HoverModel, position: HoverPosition): { expression: string; lineNumber: number; startColumn: number; endColumn: number } | null {
+  const word = model.getWordAtPosition(position)
+  if (!word) return null
+  const line = model.getLineContent?.(position.lineNumber) ?? word.word ?? ''
+  const start = Math.max(0, word.startColumn - 1)
+  const end = Math.max(start, word.endColumn - 1)
+  const isPart = (char: string): boolean => /[A-Za-z0-9_.:]/.test(char)
+  let left = start
+  while (left > 0 && isPart(line[left - 1])) left -= 1
+  // 光标词即链首段：只返回该段（向右扩展会把 this 吃成 this.canUpdate）
+  if (left === start) {
+    const head = line.slice(start, end).trim()
+    return head ? { expression: head, lineNumber: position.lineNumber, startColumn: start + 1, endColumn: end + 1 } : null
+  }
+  let right = end
+  while (right < line.length && isPart(line[right])) right += 1
+  const expression = line.slice(left, right).trim()
+  return expression ? { expression, lineNumber: position.lineNumber, startColumn: left + 1, endColumn: right + 1 } : null
+}
+
+/**
+ * 组装调试块 HTML（头行 + 类型 + 变量树；全部动态文本转义后拼进 supportHtml 片段）。
+ * ⚠️ 钩子一律用 data-*：markdown 渲染会剥掉 class（见 hoverTree.ts 常量区注释）。
+ * @author ddj 2026年09月21号
+ * @param expression 光标处表达式
+ * @param value 求值结果
+ * @param type 值类型（可空）
+ * @param treeHtml 变量树片段（可空）
+ * @returns 单块 HTML
+ */
+export function blockHtml(expression: string, value: string, type: string, treeHtml: string): string {
+  const head = '<div ' + HEAD_ATTR + '="1">'
+    + '<span ' + EXPR_ATTR + '="1">' + escapeHtml(expression) + '</span>'
+    + '<span ' + EQ_ATTR + '="1"> = </span>'
+    + '<code ' + VAL_ATTR + '="1">' + escapeHtml(value) + '</code>'
+    + '</div>'
+  const typeLine = type ? '<div ' + TYPE_ATTR + '="1">type: <code>' + escapeHtml(type) + '</code></div>' : ''
+  return '<div ' + BLOCK_ATTR + '="1">' + head + typeLine + treeHtml + '</div>'
+}
+
+/**
+ * 暂停态求值并组装 hover 内容（单个 HTML 块）。
+ * @author ddj 2026年09月21号
+ * @param monaco Monaco 命名空间
+ * @param model 文本模型
+ * @param position 光标位置
+ * @param token Monaco 取消令牌
+ * @returns hover 结果；非暂停、取不到表达式/路径、被取消时为 null
+ */
+async function dapHoverAt(monaco: any, model: HoverModel, position: HoverPosition, token: any): Promise<{ contents: Array<{ value: string; supportHtml?: boolean }>; range: unknown } | null> {
+  const snapshot = dapStore.getSnapshot()
+  if (snapshot.phase !== 'paused' || token?.isCancellationRequested) return null
+  const target = expressionAt(model, position)
+  if (!target || !isEvalExpr(target.expression)) return null
+  const path = pathOfModel(model)
+  if (!path) return null
+  const result = await dapStore.evaluate(target.expression, snapshot.selectedFrameId)
+  if (/^syntax err/i.test(result.result)) return null
+  if (token?.isCancellationRequested) return null
+  let treeHtml = ''
+  if (result.ref > 0) {
+    const children = await dapStore.variables(result.ref)
+    if (token?.isCancellationRequested) return null
+    // 可展开树：首层随 hover 取回，点「▸」才懒加载下一层（绑定见 hoverTree.ts）
+    treeHtml = initialHtml(createTreeState(treeKeyOf(target, path), children))
+  }
+  return {
+    contents: [{ value: blockHtml(target.expression, result.result, result.type ?? '', treeHtml), supportHtml: true }],
+    // 必须 new：Monaco 的 Range 是 ES class（createMonacoBaseAPI 导出类本体），
+    // 无 new 调用抛 TypeError，被 getHover 的逐 provider try/catch 吞掉 →
+    // 表现为「暂停态只有 LSP 浮窗、没有调试值行」。
+    range: new monaco.Range(target.lineNumber, target.startColumn, target.lineNumber, target.endColumn),
+  }
+}
+
+/**
+ * 注册暂停态 DAP hover provider（幂等，跨插件重载会先清理旧 provider）。
+ * @author ddj 2026年09月29号
+ * @param monaco Monaco 命名空间
+ */
+export function registerDapHover(monaco: any): void {
+  if (!monaco?.languages?.registerHoverProvider) return
+  const host = typeof window === 'undefined' ? null : window as any
+  host?.[GLOBAL_KEY]?.dispose?.()
+  const disposable = monaco.languages.registerHoverProvider(['lua'], {
+    provideHover: async (model: HoverModel, position: HoverPosition, token: any) => {
+      try {
+        return await dapHoverAt(monaco, model, position, token)
+      } catch {
+        return null // 异常不外抛：Monaco 会把整个 provider 的结果丢弃
+      }
+    },
+  })
+  if (host) host[GLOBAL_KEY] = { dispose: () => disposable?.dispose?.() }
+}
+
+/** 注销 DAP hover provider。 */
+export function disposeDapHover(): void {
+  const host = typeof window === 'undefined' ? null : window as any
+  host?.[GLOBAL_KEY]?.dispose?.()
+  if (host) delete host[GLOBAL_KEY]
+}

package/src/client/dap/hoverMode.ts

@@ -0,0 +1,159 @@
+/**
+ * dsh-vscode-mode client — hover 修饰键（Alt）状态。
+ * 对齐 CodeBuddy/VS Code 调试浮窗语义：暂停态默认显示调试值，按住 Alt 切换为 LSP 信息。
+ * 切换走**显示层行级显隐**（hoverTree.applyAltToHovers）：不重算 hover、不重跑 provider，
+ * 因此不受 Monaco「同 anchor 直接早退」影响；状态同步不依赖单一键事件——任意带 altKey 的输入
+ * 事件都会校正；且**调试浮层可见时消费裸 Alt**——否则 Chromium/宿主把 Alt 当菜单键会把焦点
+ * 抢出页面（实测：每次 Alt 后约 4ms 页面失焦、要 4~5s 才回来），此后键事件到不了页面，
+ * 切换只能等下一次鼠标移动自愈，观感就是「按下/松开都要等一会儿」。
+ * 只读监听（capture 阶段）；安装幂等 + 可卸载，跨插件重载经 window 标记认领。
+ * 作者 ddj 2026年09月21号
+ */
+import { applyAltToHovers, hasDebugHover } from './hoverTree.js'
+
+// --region 常量与状态
+/** 跨插件重载认领标记（存卸载函数）。 */
+const MODE_GLOBAL = '__edrvHoverModeWatch__'
+/** Alt 引发的抢焦点窗口（ms）：该窗口内的 blur 不回退状态（见 onBlur）。 */
+const BLUR_GRACE_MS = 500
+/** Alt 是否按住（供 hover provider 同步判定，无需异步等待）。 */
+let altHeld = false
+/** 最近一次「Alt 按住」键事件时间戳（blur 条件复位用）。 */
+let lastAltAt = 0
+/** Alt 状态变化订阅者。 */
+const altListeners = new Set<(held: boolean) => void>()
+// --endregion
+
+/**
+ * 更新 Alt 状态：仅在真正变化时同步显示层并通知订阅者。
+ * @author ddj 2026年09月21号
+ * @param next 新状态
+ */
+function setAlt(next: boolean): void {
+  if (altHeld === next) return
+  altHeld = next
+  applyAltToHovers(next)
+  for (const fn of Array.from(altListeners)) {
+    try { fn(next) } catch { /* 单个订阅异常不影响其它订阅者 */ }
+  }
+}
+
+/**
+ * 订阅 Alt 状态变化。
+ * @author ddj 2026年09月21号
+ * @param fn 变化回调（参数为当前是否按住）
+ * @returns 退订函数
+ */
+export function onAltChange(fn: (held: boolean) => void): () => void {
+  altListeners.add(fn)
+  return () => { altListeners.delete(fn) }
+}
+
+/**
+ * Alt 是否按住。
+ * @author ddj 2026年09月21号
+ * @returns 是否按住
+ */
+export function isAltHeld(): boolean {
+  return altHeld
+}
+
+/**
+ * 设置 Alt 状态（测试注入用；运行期由监听器维护）。
+ * @author ddj 2026年09月21号
+ * @param on 是否按住
+ */
+export function setAltHeld(on: boolean): void {
+  setAlt(Boolean(on))
+}
+
+/**
+ * 是否应消费裸 Alt：仅 Alt 单键（无 Ctrl/Shift/Meta）且有调试浮层可见。
+ * 消费 = preventDefault + stopPropagation，阻止浏览器/宿主把 Alt 当菜单键抢走焦点
+ * （焦点一旦移出页面，后续键事件到不了页面，切换只能等下一次鼠标移动自愈）。
+ * @author ddj 2026年09月21号
+ * @param ev 键盘事件（仅取修饰键字段，便于单测）
+ * @param debugHoverVisible 是否有可见的调试浮层
+ * @returns 是否消费该事件
+ */
+export function consumesBareAlt(ev: { key: string; ctrlKey?: boolean; shiftKey?: boolean; metaKey?: boolean }, debugHoverVisible: boolean): boolean {
+  return ev.key === 'Alt' && !ev.ctrlKey && !ev.shiftKey && !ev.metaKey && debugHoverVisible
+}
+
+/**
+ * Alt 键事件：消费（必要时）+ 记录时间（供 blur 条件复位判断）+ 同步状态。
+ * @author ddj 2026年09月21号
+ * @param ev 键盘事件
+ */
+function onAltKey(ev: KeyboardEvent): void {
+  if (ev.key !== 'Alt') return
+  if (consumesBareAlt(ev, hasDebugHover())) {
+    ev.preventDefault()
+    ev.stopPropagation()
+  }
+  lastAltAt = Date.now()
+  setAlt(ev.type === 'keydown')
+}
+
+/**
+ * 任意输入事件的 altKey 校正（键事件被吞时的兜底）。
+ * @author ddj 2026年09月21号
+ * @param ev 鼠标/键盘事件
+ */
+function onAnyInput(ev: Event): void {
+  const held = Boolean((ev as MouseEvent).altKey)
+  if (held) lastAltAt = Date.now()
+  setAlt(held)
+}
+
+/**
+ * 窗口失焦复位（条件）：刚看到 Alt 键事件则不复位
+ * （既可能是宿主菜单抢焦点的 blur，也可能是紧邻 Alt 的页内元素级 blur）。
+ * @author ddj 2026年09月21号
+ */
+function onBlur(): void {
+  const since = lastAltAt ? Date.now() - lastAltAt : -1
+  if (since >= 0 && since < BLUR_GRACE_MS) return
+  setAlt(false)
+}
+
+/**
+ * 安装 Alt 跟踪（幂等）。
+ * keydown/keyup 记 Alt；任意带 altKey 的输入事件（含 mousemove/mousedown/wheel）校正——
+ * 宿主吞掉 Alt 键事件时也能随下一次输入自愈；blur 仅在「不是刚按 Alt」时复位。
+ * @author ddj 2026年09月21号
+ */
+export function installHoverMode(): void {
+  if (typeof window === 'undefined') return
+  const host = window as unknown as Record<string, unknown>
+  if (typeof host[MODE_GLOBAL] === 'function') return // 上一代已安装（window 跨重载存活）
+  const bound: Array<[string, EventListener]> = [
+    ['keydown', onAltKey as EventListener],
+    ['keyup', onAltKey as EventListener],
+    ['keydown', onAnyInput as EventListener],
+    ['mousemove', onAnyInput as EventListener],
+    ['mousedown', onAnyInput as EventListener],
+    ['wheel', onAnyInput as EventListener],
+    ['blur', onBlur as EventListener],
+  ]
+  for (const [type, fn] of bound) window.addEventListener(type, fn, true)
+  applyAltToHovers(altHeld) // 已存在的 hover 按当前状态对齐
+  host[MODE_GLOBAL] = (): void => {
+    for (const [type, fn] of bound) window.removeEventListener(type, fn, true)
+    altHeld = false // 卸载路径直接复位，不再触发重算
+  }
+}
+
+/**
+ * 卸载 Alt 跟踪（插件重载/卸载时调用）。
+ * @author ddj 2026年09月21号
+ */
+export function disposeHoverMode(): void {
+  if (typeof window === 'undefined') return
+  const host = window as unknown as Record<string, unknown>
+  const off = host[MODE_GLOBAL]
+  if (typeof off === 'function') off()
+  delete host[MODE_GLOBAL]
+  altHeld = false
+  lastAltAt = 0
+}