Scroll dead zone: rail wheel gestures onto their dominant axis (input.scrollDeadZone)

[mstrobel]

Implements the scroll dead zone behind the existing input.scrollDeadZone user option (reserved until now): wheel gestures rail onto their dominant axis, so the stray cross-axis ticks a trackpad sheds during fast one-axis scrolling stop nudging the other axis.

Why it's a stream filter, not a delta clamp

Terminals quantize scrolling into single-axis, whole-notch SGR events (±120, one axis per event). Trackpad drift therefore arrives as isolated H ticks interleaved into a stream of V ticks — there is no diagonal delta to clamp, only a stream to filter. That makes it a natural IInputTransformer (whose own doc names filters as the intended use), sitting beside MouseClickSynthesizer and sharing its posture: purely synchronous, no timers, every decision made inline on the event's own Timestamp, deterministic to test.

The gesture model

A gesture is a run of wheel events with no 200 ms gap; its first event locks the axis. Same-axis ticks pass through; cross-axis ticks are absorbed into a tug-of-war charge (each absorbed tick adds its magnitude; each same-axis tick discharges twice its own). Reaching 360 units — three notches — re-rails the lock and delivers the breaking event.

The charge is what separates intent from accident: a real direction change looks like the primary stream stopping, so sustained cross ticks accumulate to the threshold in a fraction of a second, while drift — isolated ticks between dense primary ticks — is discharged before it can ever get there. The absorbed ticks are never replayed; that would turn the protection into a deferred jump.

Deliberate trades, chosen over latency:

• The first tick decides the lock. Buffering the gesture head would distinguish lead-drift from intent, but only by adding a timer and delivery latency to everything; a wrongly-seeded lock self-corrects through the break valve instead.
• Diagonal wobble rails to the dominant axis. That is what the option advertises; turning it off restores raw deltas.
• Raw axes, modifiers ignored — ScrollViewer's Shift+wheel→horizontal convention maps a railed raw-Y gesture exactly as it mapped the unfiltered one.

Wiring: always assembled, toggled live

The §10.4 device chain is single-shot, so the filter is always in it (disabled = one-branch pass-through) and UIApplication.ScrollDeadZoneEnabled flips a volatile on the live instance — no reassembly, order-independent with startup (the field carries the value into assembly; the setter forwards after), and renegotiation needs nothing: the chain survives ChangeCapabilities, and the filter alters no capabilities, so ApplyDecorationProjections is untouched. Startup applier and UserOptionsSession.ApplyLive both consume the key; the catalog row drops ReservedForFuture, so the Options dialog toggle now works.

What adversarial review caught

A multi-agent review pass confirmed one real algorithm bug before merge: the break valve originally existed only on the pure-cross leg, so a cross-dominant mixed stream (deliberate push with a grazing locked-axis component — synthesized/high-res sources only; terminal input can't produce it) could never re-rail while its charge grew without bound. The valve now lives on both legs, pinned by test. It also drove: startup-file coverage added to ResolvedOptions_AreInForceForTheFirstStamp per that test's every-applied-key convention, WheelAxisLockOptions as a sealed record in its own file per sibling idiom, and honest doc wording for the lazy disable-reset.

Testing

All three lanes are covered: the persisted startup file, the session live-apply, and — end to end — raw SGR wheel bytes through SendBytes, the one headless entry that exercises the real pump and decorated chain (SendInput deliberately bypasses it).

Everything was proven red-first: 13/17 core tests fail with the filter neutered, both E2E tests fail with the chain wiring removed, and the two review-driven tests each fail under precisely the variant they pin (missing mixed-leg valve / hard-reset discharge).

Cursorial.Core.Tests 1,065 · Cursorial.UI.Tests 3,457 — all green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A4i5CZSjkU1TbAgiYBomhL