Skip to content

🖱️ Mouse support for interactive TUI (EPIC) #166

Description

@shouze

Context

The interactive TUI (src/tui.ts) is keyboard-only. Users must use arrow keys and shortcuts to fold/unfold a repo's extracts (▸/▾), toggle selection (✓) on repos/extracts, and page through long result lists (Page Up/Down, Ctrl+U/D). Terminal mouse reporting (xterm/SGR protocol) is a standard, dependency-free mechanism that would let users click the fold arrow, click a checkbox, or scroll with the wheel — closer to a GUI interaction model and more discoverable for new users.

Solution

Add mouse support to the TUI using the standard SGR mouse-reporting protocol (\x1b[?1000h\x1b[?1006h), parsed on the same raw stdin channel already used for keyboard input in runInteractive(). No new dependency is introduced (picocolors remains the only styling dependency per AGENTS.md).

Sub-issue Feature Scope
Mouse tracking foundation Enable/disable protocol + escape-sequence parsing pipeline Infrastructure, blocks the two below
Click-to-toggle Fold/unfold (â–¸/â–ľ) and select/deselect (âś“) on repo/extract rows MVP interaction
Scroll-wheel support Wheel-up/down mapped to existing scroll logic Depends on foundation
UI consistency Dimmed/inactive âś“ instead of blank space for deselected checkboxes Independent, can ship first

Acceptance Criteria

  • All sub-issues are closed and merged.
  • Clicking the fold arrow, clicking a checkbox, and using the scroll wheel all work in at least one common terminal (iTerm2 or Terminal.app on macOS, plus one Linux terminal noted in manual testing).
  • No new runtime dependency was added.
  • Mouse tracking is reliably disabled on exit (including Ctrl+C) — verified manually that the terminal doesn't stay in mouse-reporting mode after the process exits.
  • Keyboard-only usage is fully unaffected (regression-free).

Definition of Done

  • bun test passes.
  • bun run lint passes.
  • bun run format:check passes.
  • bun run knip passes (no unused exports/imports).
  • bun run build.ts compiles successfully.
  • New pure logic (hit-testing, column detection, escape-sequence parsing helpers) lives in a testable module with a companion *.test.ts, per the pure-function-first architecture in AGENTS.md.
  • Documentation updated: docs/reference/keyboard-shortcuts.md documents mouse interactions; README.md interactive-mode section mentions mouse support if applicable.
  • Changelog / release notes entry prepared per AGENTS.md § Release process (minor release).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions