fix: honor scroll duration across platform plumbing

[thymikee]

Summary

Modularizes scroll command plumbing so macOS desktop scroll behavior no longer requires repeated per-layer flag, duration, result, and runner trait glue.

Details

Before: adding a scroll option crossed command projection, runtime gestures, dispatch, Apple runner assembly, and trait metadata. After: shared scroll command helpers, metadata flag projection, Apple scroll result/runner helpers, and a runner trait manifest own those decisions.

Touched files: 17. Scope stayed within command/projection, scroll runtime/dispatch, and Apple runner plumbing.

Validation

Verified with local formatter on the touched file, focused Vitest scroll/iOS runtime suite (3 files, 132 tests), TypeScript project check, and oxlint. Earlier branch validation also passed full unit suite, integration smoke tests, fallow audit, and broader focused command/batch/runner trait tests. Claude CLI external review was attempted but blocked by approval policy because it would send private diff content externally.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	+2.4 kB
JS gzip	432.7 kB	433.5 kB	+850 B
npm tarball	570.4 kB	571.3 kB	+864 B
npm unpacked	1.9 MB	1.9 MB	+2.7 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.0 ms	26.7 ms	+0.7 ms
CLI --help	47.3 ms	46.3 ms	-1.0 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/9722.js	+1.0 kB	+332 B
dist/src/2948.js	+676 B	+306 B
dist/src/9919.js	+161 B	+65 B
dist/src/input-actions.js	+85 B	+34 B

[thymikee]

Fresh review on the latest head found two issues to address before merge:

1. src/platforms/linux/input-actions.ts: the xdotool scroll path now ignores the stepCount passed by runPacedScrollSteps for non-paced scrolls and always emits one xdotool click. Previously this used click --repeat , so default and amount/pixel-based Linux scrolls now under-scroll unless durationMs is set. Please make the xdotool callback honor stepCount, for example by passing it through to --repeat.

2. src/utils/cli-flags.ts / src/commands/interaction/metadata.ts: duration docs still describe desktop-only wheel duration, but the current plumbing forwards/reports durationMs more broadly. Please either keep duration platform-scoped in behavior, or update the public CLI/MCP metadata so the agent-facing contract matches the implementation.

Also note residual risk: the review found provider-backed macOS route coverage, but not live macOS desktop app verification evidence in the PR body.

[thymikee]

Reviewed the latest head. The two issues already noted above (Linux xdotool dropping stepCount, and the desktop-only duration docs) are the blockers — I independently confirm the Linux one is a real under-scroll regression: the xdotool callback ignores its stepCount arg, so the non-paced path emits a single xdotool click instead of the old click --repeat <scrollCount>, moving ~1/5 as far unless durationMs is set. The ydotool callbacks thread stepCount correctly, so the fix is just async (stepCount) => xdotool('click', '--repeat', String(stepCount), button).

Two additional notes from my pass:

1. Scope creep vs. the title. Despite "refactor: modularize scroll command plumbing", the diff adds new duration-honoring behavior to Linux, web (runPacedScroll), Android (swipe duration), and tvOS (remote-press hold). That's a behavior change, not pure restructuring — and it's exactly where the Linux regression slipped in. Consider splitting the behavior extension into its own PR, or retitling so reviewers scrutinize runtime behavior and not just structure.

2. Web fractional step distance (minor). buildPacedScrollSteps computes stepDistance = requestedDistance / stepCount and forwards it via String(distance), which can produce values like "33.333333" to the agent-browser scroll command. Worth confirming it accepts fractional pixels, or rounding the step distance.

CI is still pending.

---

Generated by Claude Code

[thymikee]

Addressed the review comments in 5c0e3e850:

• Restored Linux xdotool non-paced scroll distance by passing stepCount through to xdotool click --repeat <count> ..., with regression coverage.
• Updated scroll duration metadata/help wording so durationMs is no longer described as desktop-only.
• Retitled the PR to reflect the runtime behavior change, not just refactoring.
• Adjusted web paced scroll to split pixel distances into integer steps, avoiding fractional pixel arguments to agent-browser scroll.

Local checks passed: focused Vitest suite, typecheck, oxlint, and fallow. GitHub checks are running on the new commit.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-25 08:12 UTC