fix(cli): improve interactive startup and short-terminal TUI

[aidenybai]

Why

After interactive project selection, React Doctor performed Git scope detection and project preparation before mounting scan feedback. On larger repositories this left the terminal looking stalled even though work had started.

The experimental TUI also devoted most of a short terminal to score and diagnostic-detail chrome, leaving almost no issue list. In tall stacked terminals it did the opposite: expanded the list into a wall that pushed the selected finding's evidence far below it. Selected findings became dim as soon as they were marked read, the code frame floated in a heavy box, and the one-line footer crowded counts, position, and every shortcut together. Repeated live diagnostics could additionally produce duplicate React-key warnings. The fix-action chooser forced ANSI black and white backgrounds, which some terminal themes remapped into a gray slab with an unreadable selected row.

What changed

• start the existing scan spinner as soon as project selection resolves
• pause and resume startup feedback around the optional scope prompt
• stop startup feedback when single- or multi-project scan progress takes ownership
• record scan.feedback_delay to track selection-to-feedback latency
• switch reports at 28 rows or fewer to the existing compact score and scrollable ranked issue list
• preserve the full face, animated score bar, projection, and branding in regular-height reports
• cap tall stacked reports at 16 navigable list rows so selected evidence stays nearby
• keep the active finding bright after it becomes read, with a cyan pointer and severity-colored content
• align category, severity, location, source evidence, fix guidance, and docs into one lightweight detail panel
• split the regular status bar into a counts/position row and a navigation row
• preserve Up/Down and G navigation while keeping a add CI as a discrete shortcut
• render fix actions on a dedicated, theme-safe screen with a foreground-only cyan selection pointer
• assign unique live-diagnostic keys even when findings have identical locations and rules
• record tui.compact_report_shown, tui.stacked_report_capped, tui.action_menu_opened, and tui.finding_navigated
• drive the built CLI through project selection in a real PTY with delayed Git
• run the startup recording against the existing pinned shadcn-ui/ui delta-audit fixture
• record the startup handoff, short-terminal TUI, and fix-action chooser as GIF and MP4 in PR CI
• publish a sticky PR preview comment with a downloadable recording artifact
• add a patch changeset for react-doctor

Parity was not run because this changes CLI progress and presentation, not lint detector behavior.

Test plan

• nr test — 15 tasks, 223 files, and 2,335 tests passed
• nr test tests/ink/scan-app.test.tsx — 13 focused TUI tests passed after restoring the full score card
• nr typecheck — 16 tasks passed
• nr lint — passed with existing fuzz-corpus warnings
• nr format:check — passed
• nr build — 10 build tasks passed
• nr smoke:json-report — schema v3 full report passed
• nr smoke:tty-prompt — real project selection reached Scanning... before delayed Git completed
• pinned shadcn-ui/ui@68e1f17 — selected the real v4 workspace and completed a clean startup scan
• built CLI in a 22-row PTY — compact list rendered, Down and G navigated, and q exited without a CI prompt
• built CLI against the real same-next fixture at 105×60 — the original score card remained intact; all 1,391 findings stayed navigable; the active finding remained high-contrast; evidence and the two-line footer rendered cleanly
• bash -n scripts/setup-terminal-recording.sh — passed
• nlx react-doctor@latest design --verbose --scope changed --yes — no design issues
• nlx react-doctor@latest --verbose --scope changed --yes — 100/100

Product brief

Interactive feedback and report hierarchy

• Job: make ongoing work and the highest-priority findings visible immediately, then make large result sets fast to triage without discarding the score card's identity.
• Reuse: keep the existing spinner, score face/bar/projection, diagnostic grouping, scroll viewport, detail renderer, status bar, keyboard model, and cyan foreground selection pattern.
• Metric: scan.feedback_delay measures startup responsiveness; tui.compact_report_shown and tui.stacked_report_capped measure responsive layout use; tui.action_menu_opened measures chooser adoption; tui.finding_navigated records once when a user moves beyond the initially selected finding.
• Compatibility: automatic presentation only; no flag, report schema, score, Action input, or package API change.
• Kill metric: reconsider either responsive branch if it is used by under 1% of TUI reports across two releases, revert the 16-row cap if triage-navigation complaints increase, revert the hierarchy pass if finding navigation does not improve or visual complaints increase across two releases, or simplify/remove the chooser if under 1% of TUI runs open it across two releases.

PR recording

• Job: give maintainers visual proof of terminal UX changes without checking out the branch.
• Reuse: extend the existing PTY smoke fixture, pinned delta-audit corpus, and sticky-comment pattern.
• Metric: at least 95% of PR revisions should produce the recording artifact successfully.
• Compatibility: repository CI only; no Action input or runtime contract change.
• Kill metric: remove the recording workflow if non-product flakes exceed 5% over 50 PR revisions or reviewers do not use it.

---

Note

Low Risk
Changes are limited to CLI progress UX, experimental TUI presentation, telemetry, and CI recording; scan logic and report schemas are unchanged.

Overview
Shows Scanning... immediately after interactive project selection, pausing only for the optional scope prompt while Git diff/setup runs, and records scan.feedback_delay. The PTY smoke test now asserts that feedback appears before a delayed git diff finishes.

The experimental TUI picks compact, stacked, or split layouts from terminal size: short viewports get a one-line score header and list-only report; tall stacked views cap the list at 16 rows; wide terminals keep the side-by-side layout. Finding rows stay severity-highlighted when read; detail panels are flattened; the fix menu is a full-screen cyan-themed screen instead of black/white overlays; live scan lines get disambiguated React keys. New TUI telemetry counters cover compact/capped layouts, action menu opens, and first navigation past the initial finding. experimental-tui also forwards --no-supply-chain.

PR CI adds a VHS workflow that records startup + TUI flows and posts a sticky preview comment with GIF/MP4 artifacts.

^{Reviewed by Cursor Bugbot for commit 4ed5188. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@1426

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@1426

npm i https://pkg.pr.new/react-doctor@1426

commit: 4ed5188

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit 4ed5188.}

[github-actions]

Interactive terminal E2E

Recorded from the built CLI at 4ed5188 in a real terminal. The fixture holds Git busy for three seconds, so Scanning... must appear immediately after project selection, then exercises the compact interactive report.

Download the GIF and MP4 artifact

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4ed5188. Configure here.}