1jehuang / 1jehuang/jcode

[Windows] Mouse wheel scrolls pre-launch terminal scrollback instead of the transcript (Alacritty / ConPTY hosts)

Open
#956 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

autonomous: no bug priority: high triage: needs-decision
Dominant language
Rust
Stars
19.9k
Forks
2.3k
Avg merge
2d 7h
Merged PRs (30d)
30

Description

Environment

  • OS: Windows 10 / 11
  • Terminal: Alacritty (ConPTY-hosted console app)
  • jcode: v0.75.5
  • Config: mouse_capture = true (default)

Current behavior

  1. Launch jcode in Alacritty on Windows.
  2. Scroll the mouse wheel up.
  3. The screen shows content from before jcode was launched (the terminal's own scrollback).
  4. Keyboard scrolling works correctly: PageUp/PageDown and line-by-line scrolling move through jcode's transcript.

Expected behavior

The wheel should scroll jcode's transcript, as it does in Windows Terminal.

Root cause

  • jcode enters the alternate screen (\e[?1049h via ratatui::init) and enables mouse reporting (?1000h/?1002h/?1003h/?1006h plus ENABLE_MOUSE_INPUT on Windows).
  • On Windows, third-party terminals like Alacritty host console apps through ConPTY. ConPTY intercepts the alternate-screen and mouse-mode sequences and maintains that state internally in conhost, without forwarding it to the host terminal (microsoft/terminal#381).
  • Alacritty therefore never learns that jcode is in the alt screen or that mouse reporting is on. Wheel events fall back to Alacritty's main-screen scrollback (the pre-launch shell content) and never reach jcode as mouse events.
  • Keyboard events are unaffected because they travel through the console input path.
  • The same symptom occurs with other TUIs on Windows + Alacritty (alacritty/alacritty#7115), so it is not jcode-specific, but jcode can work around it app-side.

Suggested fix (jcode side)

Enable ConPTY passthrough mode on Windows when running under a pseudoconsole:

  • Call SetConsoleMode(stdout_handle, mode | ENABLE_PASSTHROUGH_MODE) (0x20000).
  • In passthrough mode conhost stops intercepting VT output, so the alternate-screen and mouse-mode sequences reach Alacritty directly and real SGR mouse events come back, making wheel scrolling behave like Linux/macOS or Windows Terminal.
  • References: microsoft/terminal#1173, microsoft/terminal#1985.
  • Feature-detect: the flag requires a recent conhost. If SetConsoleMode fails, fall back to the current Windows VT mouse-sequence path (Windows Terminal keeps working as today).
  • Verify crossterm's console API usage (size queries, input reads) still works while passthrough is active, and restore the mode on exit to avoid a conhost repaint.

User workarounds today

  • Use Windows Terminal (alt screen + mouse reporting work there).
  • Or an Alacritty binding that maps the wheel to PageUp/PageDown key injection (coarse page scrolling, not mouse-grade).

Related

  • Possibly related to #540 (TUI input/scroll degradation).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the Windows console initialization and crossterm console API usage, then trace how stdout mode is set before the TUI starts and restored on exit. Test under Alacritty with ConPTY and under Windows Terminal, including a host where ENABLE_PASSTHROUGH_MODE is unsupported. Done means wheel events scroll the transcript in Alacritty while existing behavior remains intact elsewhere.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, devtools, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.