Discuss conservative terminal mouse policy for the TUI

What feature would you like to see?

I would like to discuss a conservative terminal mouse policy for the TUI before opening any code PR.

The previous experimental terminal mouse input PRs (#460 and #463) focused on clicking inside the main input editor to move the cursor. This request is related, but the target behavior is different: route only the mouse interactions that make the transcript usable while preserving the host terminal's native selection/copy/paste mental model as much as possible.

Proposed policy:

• Default to a conservative terminal mouse mode that enables SGR button/wheel events, but avoids drag-motion tracking.
• Keep app-level routing for low-risk targets:
  • wheel scrolling in the transcript
  • jump-to-bottom control
  • a narrow scrollbar affordance
  • right-click paste into the editor when the app consumes that event
• Add an escape hatch such as KIMI_TUI_DISABLE_MOUSE=1 or KIMI_TUI_MOUSE_POLICY=off so users can return to fully native terminal mouse behavior.
• When the app consumes a plain left-click selection attempt in transcript text, show a short hint telling users to hold Shift while dragging to select terminal text.

The goal is not to make terminal mouse behavior feel like a GUI. The goal is to make the TUI scrollable and clickable without surprising users who expect terminal-native selection and copy/paste to keep working.

Additional information

Why I think this is worth discussing before a PR:

• Terminal mouse reporting changes native selection behavior in many terminals; #460/#463 already called out the need for Shift-drag.
• A direct broad PR would be hard to review. The local prototype currently includes a larger spatial routing foundation, scroll handling, paste handling, resize-bound updates, and policy/hint work. That should be split before upstream review.
• The proposed policy is intentionally narrower than full editor mouse input. It keeps text selection guidance and an explicit off switch as first-class behavior rather than treating selection as an incidental caveat.

Related prior work:

• #460: feat: add experimental terminal mouse input
• #463: feat: add experimental terminal mouse input

Local validation already run on the prototype:

• pnpm --filter '@moonshot-ai/kimi-code' typecheck
• pnpm --filter '@moonshot-ai/kimi-code' test clipboard-text mouse-mode sgr-mouse-parser spatial-router spatial-routing-integration root-render-harness footer-context
• git diff --check c857f90d..HEAD for the narrow policy/hint diff

Pending before any code PR:

• Human testing of terminal selection, Shift-drag selection, wheel scrolling, jump-to-bottom, right-click paste, resize behavior, and the mouse-off escape hatch.
• Scope split from the current prototype into a small foundation PR and a smaller policy/hint PR, or another shape maintainers prefer.

The main design question: would maintainers prefer this conservative mouse policy direction, or should terminal mouse reporting remain limited to an explicit experimental editor-input feature?

Start by reading prior terminal mouse work in #460 and #463, then inspect the local prototype and its existing validation commands. Review the typecheck and mouse-related test targets listed in the issue, followed by human testing of selection, scrolling, paste, resize, and the off switch. Done means maintainers agree on the policy and the prototype is split into an acceptable PR scope.