fix(android): ease controlled scrolls within the requested duration

[thymikee]

Summary

Replace Android’s controlled-scroll braking tail from #2372 with easing in the sampling owner: accelerate for one frame, then decelerate through release.

scroll down --pixels 900 --duration-ms 300 keeps its 300ms duration and 21 events, without jitter, an appended tail, or a reduced duration ceiling. scroll top and scroll bottom retain inertial sampling.

Nine files changed. Includes help/docs, ADR 0013’s controlled-versus-linear sampling contract, package-owned property tests and generator, and the provider integration duration assertion. No added code comments.

Closes #2371.

Validation

• Rebased head e7723f5ec0: pnpm check:affected --run passed; CI pending.
• 38 focused tests passed during review cleanup; the moved property remains selected by the affected gate.
• Earlier live evidence at f1518b77db5e98bd2b60905dddf239eb490575bf: a 900px/300ms drag moved Settings 829px and RN ScrollView 830px on Pixel 7/API 36 and Pixel 9/API 37. Pixel 7 also measured 750px at 120ms and 877–878px at 10000ms; inertial bottom traversal passed.
• Android production implementation is unchanged from that live-verified head. Reduced momentum does not guarantee an exact content offset.
• Earlier broader lifecycle verification was interrupted by host sleep; observability was not reached. Sessions were cleaned up.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-10 08:15 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.53 MB	4.53 MB	-780 B
Package (unpacked)	4.53 MB	4.53 MB	-780 B
Package (download)	1.34 MB	1.34 MB	-364 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.3 ms	28.9 ms	+0.7 ms
CLI --help	78.8 ms	77.6 ms	-1.2 ms

[thymikee]

The easing implementation and reported Settings/RN evidence look sound at f1518b7, and this is a simpler alternative to #2372 rather than a change to stack on top of it. Two cleanup items remain: update ADR 0013, which still requires linear Android transport sampling, to describe controlled easing versus inertial/general plans; move the new Android-lowering property test beside its package-owned implementation. Android smoke passes. Linux failed during apt setup and iOS failed in an unchanged fixture interaction, so those failures appear unrelated, but CI is not fully green.

[thymikee]

This branch now conflicts with main, and #2372 has merged. Since this proposal was presented as an alternative to #2372, please reconcile the intended controlled-scroll behavior with that implementation before rebasing; the earlier ADR and test-location findings also remain. Validate the combined behavior rather than carrying both fixes forward unchanged.

[thymikee]

The rebase at 4834ad2 cleanly replaces the braking tail, and the Android implementation matches the version with the reported Settings/RN evidence. Checks pass and conflicts are resolved. The two earlier cleanup items remain: update ADR 0013 to distinguish controlled easing from linear inertial/general sampling, and move the Android-lowering property test and its new arbitrary beside the package-owned implementation; rerun the focused tests and affected checks afterward.

[thymikee]

This now conflicts with main at the unchanged 4834ad2 head. Please resolve the conflict and rerun the affected checks; the two previously noted cleanup items still apply.

[thymikee]

Addressed all actionable review comments in e7723f5:

• Rebased onto current main. The easing implementation replaces the merged fix(android): honor scroll releaseBehavior to stop the fling overshoot #2372 braking tail; both mechanisms are not retained.
• Updated ADR 0013 to distinguish controlled easing from linear inertial/general sampling and corrected the lowering module path.
• Moved the Android-lowering property and its generator beside the package-owned implementation, retaining its 40-run budget.
• Updated the provider integration assertion to the requested 350ms duration without the old 160ms tail.

The exact rebased head passes pnpm check:affected --run. Earlier focused verification passed all 38 tests. Production Android code remains identical to the live-verified implementation; previous device evidence retains its original commit attribution in the PR body. CI is pending.

[thymikee]

The cleanup is complete at e7723f5: controlled easing preserves the requested duration and endpoints, inertial sampling stays linear, and the old braking tail is removed. The production code matches the earlier live-tested Android version. No remaining code findings; iOS CI failed on the known five-second Xcode version probes before the runner build, which looks unrelated to this change.