feat(pointer): add typed mouse input and animated recording overlays

[kitlangton]

Why

Mouse-driven terminal demos need to show where an interaction happened, not just the resulting screen. Terminal Control previously required raw escape sequences for mouse input and offered no pointer feedback in exported recordings.

What Changes

Operation	Behavior
termctrl mouse demo move 12 4	Hover at zero-based column 12, row 4
termctrl mouse demo click 12 4	Send an immediate press/release pair
down, move, up	Drag with one explicitly held button
video --pointer-overlay	Add an animated pointer, defaulting to 60 fps
--pointer-reduced-motion	Keep fades without travel or press scaling

The same typed input is available through Rust sessions, session.mouse(...) in the TypeScript client, and MCP send_mouse. Ghostty uses the application's negotiated mouse protocol; disabled reporting and out-of-bounds coordinates fail before sending input.

The pointer uses 220 ms smoothstep travel, subtle press compression, and short fades. It arrives at the recorded input instant without adding delays or synthetic input. Ordinary screenshots remain unadorned, and --hide-cursor continues to mean the terminal text cursor.

Recording Clock

Mouse evidence records the delivered bytes and semantic action on the existing recording clock. Video sampling follows source time through cuts, speed changes, holds, and resizes, rather than tying animation to terminal redraws.

New recordings use format v2; current readers still accept v1. Named sessions and driver clients check capability support and request an update/restart instead of falling back to unsafe raw input.

Maintenance Review

• Share wire key encoding, output readers, standard descriptor ownership, and resolved video clip timing instead of maintaining duplicate implementations.
• Borrow frame text, retain OpenTUI renderable identity during discovery, and share normalized terminal frames across pointer-animation cache entries.
• Preserve split color-query prefixes, skip invisible startup text, and keep original test failures when artifact capture also fails.
• Replace the obsolete standalone OpenTUI publisher with packed-artifact checks against both supported test versions. Version mismatch now fails without rewriting manifests.

Public exports, adapter input shapes, legacy recording readability, process ownership, and documented commands are preserved. The audit found no justified unused-export or dependency deletions.

Demo

The same real PTY recording exported with the overlay disabled (left) and enabled (right). This uses the included scripts/mouse-demo.ts fixture, not an external production application. The edit includes 0.8x and 1.4x clips, deliberate holds, and a viewport resize. Both exports are 60 fps.

pointer-review-comparison.mp4

Scope

Typed mouse input and presentation-only video overlays, plus focused cleanup and regression fixes from a repository-wide review. Live recording controls (#5), additional MCP recording/artifact tools (#7), and the broader tape/workspace automation in #18 remain separate work.

Verification

Completed: 142 Rust tests (one manual benchmark ignored), 16 client tests, and 10 OpenTUI tests. Independent reviews checked lifecycle/ownership, adapter schemas, and recording timing. All 339 decoded frames of the edited demo are identical before and after the refactors. The three new correctness regressions failed before their fixes and pass afterward.

The complete validation set is being rerun before merge; packaged-consumer and CI results will be updated here:

bun install --frozen-lockfile
cargo fmt --all -- --check
cargo test --all-targets
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release
bun run test:npm
bun run build:npm
bun run validate:npm
bun run validate:opentui
cargo package --list
cargo package