fix(cli): stabilize VP mouse interactions

[ZevGit]

What this PR does

This PR stabilizes mouse interactions in the virtualized terminal viewport. It keeps terminal mouse tracking enabled until every active mouse subscriber has been cleaned up, so a collapsed thinking block or overlay can no longer disable mouse reporting while the viewport still needs wheel or click events. It also adds scrollbar hit-testing for the virtualized list so users can click and drag the in-app scrollbar to move through long output.

Why it's needed

Virtualized viewport mode is the path that avoids terminal scrollback redraw flicker, but it needs to preserve expected terminal interactions before it can be considered safe as a default. Maintainer feedback on #5738 called out two blockers: mouse scrolling / scrollbar dragging did not work reliably, and collapsed thinking blocks could fail to open with mouse clicks. The underlying issue was that mouse mode was managed per component even though it is a global terminal setting, and scrollbar dragging had not been implemented.

Reviewer Test Plan

How to verify

Run the focused viewport mouse tests and confirm they pass. Reviewers can also run the CLI with ui.useTerminalBuffer enabled, produce enough output to show the in-app scrollbar, then verify that the mouse wheel scrolls the viewport, dragging the scrollbar moves to the expected portion of history, and clicking a collapsed thinking line opens the thinking viewer.

Evidence (Before & After)

Before: the new regression tests fail because deactivating one mouse subscriber writes the terminal mouse-disable sequence while another subscriber remains active, and scrollbar press / drag events do not move the rendered viewport. After: the regression tests pass, along with adjacent virtualized list, history item, and mouse parser tests.

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested
🐧 Linux	⚠️ not tested

Environment (optional)

Local macOS development environment with Node.js 22 workspace dependencies.

Risk & Scope

• Main risk or tradeoff: scrollbar dragging now depends on measured viewport coordinates; the behavior is limited to the existing scrollbar column and returns false for content-area clicks.
• Not validated / out of scope: this does not change the default value of ui.useTerminalBuffer; it only fixes VP mouse interaction blockers.
• Breaking changes / migration notes: none.

Linked Issues

Follow-up to #5738 maintainer feedback.

中文说明

What this PR does

这个 PR 稳定了虚拟终端视口里的鼠标交互。它会等所有活跃的鼠标订阅者都清理完之后，才关闭终端鼠标追踪，因此 collapsed thinking block 或 overlay 不会再在 viewport 仍然需要滚轮/点击事件时误关鼠标上报。它还为虚拟列表增加了滚动条 hit-test，让用户可以点击并拖动应用内滚动条浏览长输出。

Why it's needed

虚拟视口模式是避免 terminal scrollback 重绘闪屏的路径，但在考虑默认开启之前，需要先保留用户期望的终端交互。#5738 的 maintainer 反馈指出两个 blocker：鼠标滚动/滚动条拖拽不可靠，以及 collapsed thinking block 可能无法通过鼠标点击打开。根因是鼠标模式虽然是全局终端设置，却按组件单独开关；同时滚动条拖拽之前没有实现。

Reviewer Test Plan

How to verify

运行聚焦的 viewport mouse 测试并确认通过。Reviewer 也可以启用 ui.useTerminalBuffer 运行 CLI，产生足够长的输出让应用内滚动条出现，然后确认鼠标滚轮可以滚动 viewport，拖动滚动条可以移动到预期的历史位置，点击 collapsed thinking 行可以打开 thinking viewer。

Evidence (Before & After)

Before：新增回归测试会失败，因为一个鼠标订阅者失活时会写入终端鼠标关闭序列，即使另一个订阅者仍然活跃；同时滚动条按下/拖拽事件不会移动渲染窗口。After：这些回归测试通过，相邻的 virtualized list、history item 和 mouse parser 测试也通过。

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested
🐧 Linux	⚠️ not tested

Environment (optional)

本地 macOS 开发环境，使用 Node.js 22 workspace dependencies。

Risk & Scope

• Main risk or tradeoff：滚动条拖拽现在依赖测量到的 viewport 坐标；行为限制在现有滚动条列内，内容区点击会返回 false。
• Not validated / out of scope：这次不修改 ui.useTerminalBuffer 的默认值，只修复 VP 鼠标交互 blocker。
• Breaking changes / migration notes：无。

Linked Issues

跟进 #5738 的 maintainer 反馈。

[ZevGit]

Verification report for this VP mouse interaction fix:

• cd packages/cli && npx vitest run src/ui/hooks/useMouseEvents.test.tsx src/ui/components/shared/ScrollableList.test.tsx src/ui/components/shared/VirtualizedList.test.tsx src/ui/components/HistoryItemDisplay.test.tsx src/ui/utils/mouse.test.ts
  Result: passed, 5 files / 71 tests.
• npx eslint packages/cli/src/ui/hooks/useMouseEvents.ts packages/cli/src/ui/hooks/useMouseEvents.test.tsx packages/cli/src/ui/components/shared/ScrollableList.tsx packages/cli/src/ui/components/shared/ScrollableList.test.tsx packages/cli/src/ui/components/shared/VirtualizedList.tsx
  Result: passed.
• git diff --check
  Result: passed.
• npm run build
  Result: passed. Existing warnings only: Browserslist data age, large Vite chunks, and existing VSCode companion curly-rule warnings.
• npm run typecheck
  Result: failed on current upstream/main type drift unrelated to this PR. The reported failures are existing cross-package API mismatches such as missing DEFAULT_QWEN_CUSTOM_IGNORE_FILE_NAMES, AvailableModel.fastOnly/voiceOnly, ServeWorkspaceProvidersStatus.acpChannelLive, and FileSearchOptions.customIgnoreFiles; no failure pointed at the files changed here.

Regression coverage added:

• Multiple active mouse subscribers now keep terminal mouse mode enabled until the last subscriber deactivates.
• Scrollbar press / drag events now move the virtualized viewport.
• Content-area mouse press / drag events still do not move the viewport.

[ZevGit]

Post-review update:

During an additional strict self-review, I found one interaction edge case in the first revision: after a drag started on the scrollbar, moving the pointer horizontally away from the scrollbar column stopped the drag early. That made the fix less robust than a normal scrollbar drag interaction.

I amended the PR to keep an active scrollbar drag following the pointer's row until release, while still requiring the initial press to hit the scrollbar column. I also added a regression test for that case.

Fresh verification after the amend:

• cd packages/cli && npx vitest run src/ui/hooks/useMouseEvents.test.tsx src/ui/components/shared/ScrollableList.test.tsx src/ui/components/shared/VirtualizedList.test.tsx src/ui/components/HistoryItemDisplay.test.tsx src/ui/utils/mouse.test.ts
  Result: passed, 5 files / 72 tests.
• npx eslint packages/cli/src/ui/hooks/useMouseEvents.ts packages/cli/src/ui/hooks/useMouseEvents.test.tsx packages/cli/src/ui/components/shared/ScrollableList.tsx packages/cli/src/ui/components/shared/ScrollableList.test.tsx packages/cli/src/ui/components/shared/VirtualizedList.tsx
  Result: passed.
• git diff --check
  Result: passed.
• npm run build
  Result: passed, with existing warnings only.

[wenshao]

[Critical] Scrollbar drag is permanently cancelled when the cursor drifts horizontally off the scrollbar column.

During a move event, isDraggingScrollbar.current is overwritten with the return value of scrollToScrollbarLocation, which returns false when zeroBasedCol !== scrollbarCol. Any horizontal cursor drift — extremely common during a drag — flips the flag to false and silently drops all subsequent move events, even though the mouse button is still held.

Standard scrollbar UX ignores horizontal drift during a vertical drag; only left-release should end the drag.

Suggested change

	isDraggingScrollbar.current =
	if (event.name === 'move' && isDraggingScrollbar.current) {
	virtualizedListRef.current.scrollToScrollbarLocation(event);
	return;
	}

Note: scrollToScrollbarLocation also needs adjustment — during an active drag it should skip the column check and only use the row to compute the scroll offset. One approach: split into hitTestScrollbar({col, row}): boolean (called on press) and scrollToScrollbarRow(row): void (called on move), so the column check only gates the initial press.

— qwen3.7-max via Qwen Code /review

[ZevGit]

Fixed in the updated head. The scrollbar API is now split into hitTestScrollbar({ col, row }) for the initial press and scrollToScrollbarRow(row) for active drag movement. move no longer overwrites isDraggingScrollbar.current; only left-release ends an active drag. Added a regression test for horizontal pointer drift during drag.

[wenshao]

[Suggestion] The scrollbar drag test only covers a full top-to-bottom drag (row 1 → row 5, which triggers stick-to-bottom). Several important scenarios are untested:

1. Intermediate drag position — drag to row 3 of 5 and verify the viewport lands at a proportional offset (not stuck to bottom).
2. Drag with horizontal drift — once the Critical bug above is fixed, verify that dragging off the scrollbar column and back still scrolls correctly.
3. maxScroll === 0 — when data fits in the container, a click on the scrollbar column should be a no-op.
4. Boundary rows — press at trackTop (scrollRatio=0) and at trackBottom - 1 (scrollRatio=1.0).

Adding at least the intermediate-position test would cover the core scroll-ratio math that is currently only exercised at the 100% extreme.

— qwen3.7-max via Qwen Code /review

[ZevGit]

Addressed in the updated tests. Added coverage for an intermediate scrollbar drag position (row 3 of a 5-row track, verifying proportional offset instead of bottom stickiness), horizontal drift after drag start, and the maxScroll === 0 no-op case when content fits the viewport. Existing tests still cover top-to-bottom and content-area clicks.

[ZevGit]

Final update after addressing the review comments:

• Split scrollbar handling into hitTestScrollbar({ col, row }) for the initial press and scrollToScrollbarRow(row) for active drag movement.
• move no longer overwrites the drag-active flag; an active drag ends on left-release.
• Added regression coverage for intermediate scrollbar position, horizontal pointer drift during drag, and the maxScroll === 0 no-op case.

Fresh verification:

• cd packages/cli && npx vitest run src/ui/hooks/useMouseEvents.test.tsx src/ui/components/shared/ScrollableList.test.tsx src/ui/components/shared/VirtualizedList.test.tsx src/ui/components/HistoryItemDisplay.test.tsx src/ui/utils/mouse.test.ts
  Result: passed, 5 files / 74 tests.
• npx eslint packages/cli/src/ui/hooks/useMouseEvents.ts packages/cli/src/ui/hooks/useMouseEvents.test.tsx packages/cli/src/ui/components/shared/ScrollableList.tsx packages/cli/src/ui/components/shared/ScrollableList.test.tsx packages/cli/src/ui/components/shared/VirtualizedList.tsx
  Result: passed.
• git diff --check
  Result: passed.
• npm run build
  Result: passed, with existing warnings only.
• npm run typecheck
  Result: passed.

[wenshao]

@qwen-code /triage

[wenshao]

R2 APPROVE — Both R1 findings properly addressed at 3c37093.

R1 Critical (scrollbar drag cancelled on horizontal drift): Fixed by splitting the monolithic scrollToScrollbarLocation into hitTestScrollbar({col, row}): boolean (gates only the initial press) and scrollToScrollbarRow(row): void (called during drag, ignores column). isDraggingScrollbar.current is now set only on left-press and cleared only on left-release; move events no longer overwrite it. The regression test 'keeps dragging after the pointer leaves the scrollbar column' directly validates this fix.

R1 Suggestion (test coverage): All suggested scenarios are now covered — intermediate drag position (proportional offset, not stick-to-bottom), horizontal drift during drag, and maxScroll === 0 no-op.

Ref-counted mouse mode: Clean implementation. Module-level Map<WriteStream, {refs}> correctly tracks per-stdout subscriber counts; enable/disable escape sequences fire only at the 0↔1 transitions. Process exit handler registered/removed with the map lifecycle. Test verifies two-subscriber ref-counting lifecycle (enable once, disable only when both inactive, no spurious writes on unmount).

Test verification: All 49 tests pass locally (ScrollableList 13/13, useMouseEvents 1/1, VirtualizedList 20/20, mouse parser 15/15).

— qwen3.7-max via Qwen Code /review

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓ — all required sections present, bilingual, clear test plan.

On direction: this is squarely in scope. The virtualized viewport path is the project's answer to scrollback redraw flicker, and you're fixing the two mouse-interaction blockers that maintainers flagged in #5738. Stabilizing VP before it can become the default is exactly the kind of incremental hardening the project needs right now. No concerns here.

On approach: the scope feels right. Two distinct problems (mouse mode ref counting, scrollbar hit-test + drag), solved with minimal surface area across 5 files. The module-level ref-counting map for mouse mode is a clean fit — mouse mode is a global terminal setting, so a shared counter (rather than per-component toggling) is the right abstraction. The scrollbar geometry calculation reuses the existing measureElementPosition utility, which is good. No drive-by refactors or scope creep in the diff.

One question worth thinking about: the isDraggingScrollbar ref lives in ScrollableList while the actual hit-test logic lives in VirtualizedList. This split means the drag state and the geometry are in two different components. It works, but if a future interaction (e.g. horizontal scrollbar, or a different list consumer) also needs drag tracking, the ref might need to move down. Not a blocker — just noting the coupling.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓ — 所有必要章节齐全，双语，测试计划清晰。

方向：完全在范围内。虚拟视口路径是解决 scrollback 重绘闪屏的方案，你在修复 #5738 中 maintainer 指出的两个鼠标交互 blocker。在 VP 成为默认选项之前进行稳定性加固，正是项目当前需要的。没有顾虑。

方案：范围合理。两个独立问题（鼠标模式引用计数、滚动条 hit-test + 拖拽），用 5 个文件的最小改动面解决。模块级引用计数 map 很合适——鼠标模式是全局终端设置，共享计数器（而非按组件开关）是正确的抽象。滚动条几何计算复用了已有的 measureElementPosition 工具函数，很好。diff 中没有顺手重构或范围蔓延。

一个值得思考的问题：isDraggingScrollbar ref 在 ScrollableList 中，而 hit-test 逻辑在 VirtualizedList 中。这种分离意味着拖拽状态和几何计算分布在两个组件里。当前可行，但如果未来有交互需要拖拽追踪（如水平滚动条或其他列表消费者），这个 ref 可能需要下沉。不是 blocker，只是指出耦合关系。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

Code Review

Independent proposal (before reading diff): I would have used a module-level integer counter for mouse mode ref counting, and computed scrollbar position from useBoxMetrics relative coordinates. Both approaches would have worked but been less robust.

Comparison: The PR's approach exceeds my proposal in two ways:

• The Map<NodeJS.WriteStream, {refs}> pattern handles multiple stdout streams correctly (relevant for test environments or redirected output), where a plain counter would conflate them.
• Using measureElementPosition (which walks the Yoga layout tree for screen-absolute coordinates) is the right call for scrollbar hit-testing. Relative coordinates from useBoxMetrics break when the list is nested inside other containers.

Findings: No correctness bugs, security issues, or regressions found. The code is well-structured and follows project conventions.

Specific things that look good:

• acquireMouseMode/releaseMouseMode are symmetric; the process exit handler is registered/unregistered correctly with the first/last entry.
• isDraggingScrollbar is always cleared on left-release regardless of pointer position — handles the case where the user drags off the scrollbar column before releasing (also covered by the "keeps dragging after pointer leaves scrollbar column" test).
• scrollToScrollbarRow properly handles the sticky-to-bottom case when dragged to the end, matching the existing scrollBy/scrollTo patterns.
• The hit-test uses exact column match (zeroBasedCol === geometry.col) which limits interaction to the scrollbar track only — content clicks pass through untouched.

Testing

Unit Tests (worktree)

 ✓ src/ui/hooks/useMouseEvents.test.tsx (1 test)
 ✓ src/ui/components/shared/ScrollableList.test.tsx (13 tests)
 ✓ src/ui/components/shared/VirtualizedList.test.tsx (20 tests)
 ✓ src/ui/utils/measure-element-position.test.tsx (4 tests)

 Test Files  4 passed (4)
      Tests  38 passed (38)

The new useMouseEvents test verifies the core fix: with two subscribers, deactivating one does NOT emit the disable sequence, and deactivating both does. This is the regression test for the collapsed-thinking-block bug.

The new ScrollableList tests cover scrollbar drag to bottom, intermediate position, drag-off-scrollbar-column, and no-op when content fits viewport.

Dev Build Smoke Test (tmux)

The dev build starts cleanly and responds to prompts:

$ timeout 20 npm run dev -- -p 'say hello'
> node scripts/dev.js -p say hello
DEV is set to true, but the React DevTools server is not running.
Hello! How can I help you today?

Mouse Interaction Testing

SGR mouse protocol events (wheel, click, drag) cannot be meaningfully exercised through headless tmux — tmux intercepts mouse events at the session level before they reach the application as stdin escape sequences. The 14 new unit tests (which inject raw SGR sequences directly into stdin) are the correct verification layer for these interactions and all pass.

中文说明

代码审查

独立方案（读 diff 前）： 我会用模块级整数计数器做鼠标模式引用计数，用 useBoxMetrics 的相对坐标计算滚动条位置。两种方案都能用，但不够健壮。

对比： PR 的方案在两方面更优：

• Map<NodeJS.WriteStream, {refs}> 模式正确处理多个 stdout 流（在测试环境或输出重定向时有意义），而简单计数器会混淆它们。
• 使用 measureElementPosition（遍历 Yoga 布局树获取屏幕绝对坐标）是滚动条 hit-test 的正确选择。useBoxMetrics 的相对坐标在列表嵌套于其他容器时会出错。

发现： 没有正确性 bug、安全问题或回归。代码结构良好，遵循项目规范。

测试

单元测试（worktree）

4 个文件 38 个测试全部通过。

新的 useMouseEvents 测试验证了核心修复：两个订阅者时，一个失活不会发出关闭序列。这是 collapsed-thinking-block bug 的回归测试。

新的 ScrollableList 测试覆盖了滚动条拖拽到底部、中间位置、拖出滚动条列、以及内容适配视口时的无操作。

Dev Build 冒烟测试（tmux）

Dev build 正常启动并响应提示。

鼠标交互测试

SGR 鼠标协议事件（滚轮、点击、拖拽）无法通过无头 tmux 有效测试——tmux 在会话级别拦截鼠标事件。14 个新单元测试（直接注入原始 SGR 序列到 stdin）是正确的验证层，全部通过。

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

Stepping back: this PR does what it says and does it well. Two real blockers for the virtualized viewport path — mouse mode getting prematurely disabled, and missing scrollbar drag — are solved with focused, minimal changes. The ref-counting approach is actually better than what I would have written (the per-stdout Map handles edge cases a plain counter wouldn't), and reusing measureElementPosition for screen-absolute coordinates is the right call over relative useBoxMetrics.

38 tests pass (14 new, 24 regression), the dev build is clean, and there's nothing in the diff that doesn't belong there. The kind of PR you want from a fork contributor — scoped, well-tested, no surprises.

Approving. ✅

中文说明

总结：这个 PR 名副其实。虚拟视口路径的两个真实 blocker——鼠标模式被过早关闭、缺失滚动条拖拽——用聚焦且最小化的改动解决了。引用计数方案比我会写的更好（per-stdout Map 处理了简单计数器无法覆盖的边界情况），复用 measureElementPosition 获取屏幕绝对坐标也是比 useBoxMetrics 相对坐标更正确的选择。

38 个测试通过（14 个新增，24 个回归），dev build 正常，diff 中没有不属于的改动。来自 fork 贡献者的理想 PR——范围明确、测试充分、没有意外。

批准。✅

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

ignore

[chiga0]

Overview

Final Verdict: Approve — Clean, well-targeted fix for the two VP mouse interaction blockers identified in #5738. The ref-counting approach for mouse mode and the scrollbar hit-testing implementation are both correct and well-tested.

Cross-Validation

#	Finding	Reviewer	My Assessment
C1	Scrollbar drag cancelled on horizontal drift — isDraggingScrollbar overwritten by scrollToScrollbarLocation returning false	wenshao	Fixed at HEAD — API split into hitTestScrollbar (gates initial press only) and scrollToScrollbarRow (handles movement). move events no longer overwrite the drag flag; only left-release ends the drag.
S1	Scrollbar drag test only covers full top-to-bottom drag	wenshao	Fixed at HEAD — Added tests for intermediate drag position, horizontal drift after drag start, and maxScroll === 0 no-op.

No unique Critical or Major findings from my independent review.

Additional Audit Coverage

Areas I independently verified beyond existing findings:

• Ref counting lifecycle: acquireMouseMode enables SGR mode on first subscriber, releaseMouseMode disables on last. process.on('exit') registered/unregistered symmetrically. Module-level mouseModeRefs Map correctly handles multiple stdout streams as separate keys.
• SGR coordinate conversion: hitTestScrollbar correctly converts 1-based SGR coordinates to 0-based (col - 1, row - 1) before comparing with measureElementPosition results.
• Scrollbar geometry edge cases: getScrollbarGeometry() returns null when maxScroll === 0 (no scrollbar needed), scrollableContainerHeight <= 0 (container not measured), or rootRef not mounted. All callers guard against null.
• Drag stick-to-bottom: When scrollRatio reaches 1.0 (dragged to bottom), scrollToScrollbarRow sets isStickingToBottom(true) and anchors to the last item — consistent with existing scroll-to-bottom behavior.
• useImperativeHandle deps: Both hitTestScrollbar and scrollToScrollbarRow added to the dependency array — handle stays current.
• Test quality: useMouseEvents.test.tsx correctly validates the full ref-counting lifecycle (2 active → 1 active → 0 active → unmount). ScrollableList.test.tsx covers 5 drag scenarios including edge cases.

---

This review was generated by QoderWork AI