fix(contracts): state the scroll keyboard clip once for every platform

[thymikee]

Summary

First layer of #2500: the rule that keeps a scroll's swipe out of the keyboard, stated once in TypeScript, with the golden table both native runners read. iOS implements it in #2503 and Android in #2514, so nothing here moves a gesture yet.

clipScrollViewportAboveKeyboard is the whole decision: a keyboard that reaches the swipe's centre line takes the band below it, and when what remains cannot carry a swipe the command refuses with scrollKeyboardOccludesSurfaceError rather than scrolling a surface the keys own. contracts/fixtures/scroll-keyboard-policy.json is the cross-language table, so the Swift and Java lanes assert against the same rows instead of each platform inventing its own thresholds.

Behaviour stated here

• A keyboard is struck when it reaches the swipe's centre line, and a floating keyboard sitting past that line is not — its width fraction no longer decides anything.
• keyboardAvoided and keyboardMinY join a scroll response only when the clip ran, and the CLI help, MCP output schema and command docs name them here, so both platforms answer with one shape.
• The keyboard is never dismissed. Dismissing drops focus and breaks a fill/scroll/fill loop; keyboard dismiss stays an explicit command.
• The refusal code lands before any runner emits it, which is deliberate: the typed reason and its evidence keys are defined once here, and fix(scroll): keep the swipe above the keyboard, refuse when it cannot #2503 and fix(android): keep a scroll's swipe out of the IME window #2514 are what produce them.

Validation

pnpm check green at 1b8548af6d, which covers the golden parity table (18 rows, including the Android-shaped adjustPan window with only 88px of 900px left above the IME is refused and the iOS-shaped landscape keyboard leaving 28pt of a 402pt axis is refused instead of swiping under the keys), the Apple-side mapping tests, MCP metadata and the production-exports lane.

No device run belongs to this layer — it dispatches nothing. The live simulator and emulator evidence for the paths it states is posted on #2503 and #2514.

Size

11 files, 615 gross lines: one shared module, its golden table, and the surface that names its two response keys.

Part of the #2500 stack: this PR -> #2503 (iOS runner) -> #2514 (Android). Do not merge out of order.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.50 MB	4.50 MB	+2.3 kB
Package (unpacked)	4.50 MB	4.50 MB	+2.3 kB
Package (download)	1.33 MB	1.33 MB	+907 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	18.6 ms	18.8 ms	+0.2 ms
CLI --help	48.7 ms	49.0 ms	+0.2 ms

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-2537/
Built to branch gh-pages at 2026-09-12 19:09 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[thymikee]

No actionable findings on 1b8548a. The shared contract and Apple surface extraction preserves the previously reviewed source, with the dispatch changes correctly left in the dependent PRs. Typed errors, response fields, MCP schema, fixtures, help, and docs are aligned for this layer. Current checks pass and there are no conflicts. Ready for human review and merge.