fix(ios): classify the keyboard dismiss refusal by what it dispatched

Merged
TH
2d ago
+235-45

Summary

keyboard dismiss refused two different verdicts with one untyped message, so a caller had to match prose to tell them apart: a keyboard that exposes no dismiss control (nothing was sent) and a dismiss control that was tapped and left the keys up (it dispatched). The refusal behavior is unchanged; only its classification becomes typed.

The runner answers the no-dismiss-key case with its own wire code KEYBOARD_DISMISS_UNAVAILABLE, classified by the existing runner-code table. The published code contract is unchanged — it still travels under UNSUPPORTED_OPERATION through its own wire-code map — and the failure now carries details.reason: keyboard_dismiss_unavailable, details.runnerErrorCode, and dispatched: no, all visible in --json. dismissKeyboard answers a RunnerKeyboardDismissOutcome carrying dispatchedDismissal, which also decides which verdict a tvOS keyboard stayed up for.

14 files: Swift runner + protocol doc, the Apple runner classification and its tests, the dispatch-disclosure fixture, command help, and the command docs. No scope expansion beyond keyboard dismiss; no CHANGELOG.

$ agent-device keyboard dismiss --json
{"error":{"code":"UNSUPPORTED_OPERATION","message":"Unable to dismiss the keyboard: it exposes no dismiss key, …",
 "details":{"runnerErrorCode":"KEYBOARD_DISMISS_UNAVAILABLE","reason":"keyboard_dismiss_unavailable","dispatched":"no"}}}

Live simulator evidence

Head 306352ce2a. iPhone 17, iOS 27.0, UDID 0E0FCBDC-88E2-4CB6-A1DA-E148F77743F4, Xcode 27.1 (27A9275). Runner rebuilt from this branch with pnpm build && pnpm build:xcuitest; fresh state dir, so a new daemon.

A="node bin/agent-device.mjs --platform ios --udid 0E0FCBDC-88E2-4CB6-A1DA-E148F77743F4 --state-dir /private/tmp/ad-4536-state --session k4536"

No dismiss control — Agent Device Tester, Form tab, Full name field, software keyboard up with no Done/Hide key:

$A open com.callstack.agentdevicelab --relaunch; $A press @e27; $A press @e10
$A keyboard dismiss --json     # exit 1
{"success":false,"error":{"code":"UNSUPPORTED_OPERATION","message":"Unable to dismiss the keyboard: it exposes no dismiss key, and background taps are never attempted (…)","hint":"An element whose center sits behind the on-screen keyboard is refused with tap_keyboard_occludes_target; … or use keyboard enter to press the return key when submission is wanted.",
 "details":{"runnerErrorCode":"KEYBOARD_DISMISS_UNAVAILABLE","reason":"keyboard_dismiss_unavailable","dispatched":"no"}}}

A screenshot taken right after shows the full QWERTY keyboard still visible, and snapshot -i still lists the key nodes.

With dismiss control — Safari, https://the-internet.herokuapp.com/login, Password field, accessory bar with Previous/Next/Done:

$A open com.apple.mobilesafari https://the-internet.herokuapp.com/login; $A press @e16
$A keyboard dismiss --json
{"success":true,"data":{"platform":"ios","action":"dismiss","wasVisible":true,"dismissed":true,"visible":false,"mechanism":"dismissKey","message":"Keyboard dismissed via its dismiss key"}}

snapshot -i afterwards no longer lists the Previous/Next/Done toolbar.

Cleanup: close --shutdown, daemon stop --clean --state-dir /private/tmp/ad-4536-state.

Validation

Base ddbfc85566, functional head b46ac6d761; 3231d4448c and 579ad97b28 are doc/help-sentence follow-ups on review; 306352ce2a applies the review recommendations (flag rename, separate wire-code map, help sentence).

  • pnpm check:affected --run --head b46ac6d76170efc6867e22acb773d0f57afd2c14 — all runnable checks passed, exactCommit=true (format, lint, typecheck, layering, fallow, native-dupes, build, vitest-related, unit, command-docs, docs-links, docs-prose, xctest-selection, packaged-runner-swift).
  • Review follow-ups 3231d4448c and 579ad97b28 touch only the keyboard help sentence and its docs counterpart. For those: cli-help-command-usage.test.ts, cli-help-topics.test.ts, command-doc-coverage.test.ts, check:doc-prose, and the MCP-metadata check pass locally; the serialized gate for the head is owned by CI.
  • pnpm build:xcuitest (iOS + macOS) succeeded; pnpm check:xctest-selection reports the new Swift test reachable from the host lane.
  • Re-run at 306352ce2a: focused vitest (runner-error-classification, runner-contract-response, index-dispatch-disclosure, src/commands/schema, help-conformance), pnpm check:xctest-selection, pnpm build && pnpm build:xcuitest pass.
  • CI obligations: device lanes (PR iOS runner smoke, nightly XCTest) run on GitHub. Coverage passed at 579ad97.
  • Unresolved risk: no released tag contains the old details shape, and new optional keys inside the open details record are already declared additive in the wire-compat ledger, so no ledger entry was added.

🤖 Generated with Claude Code