feat: io fill replaces the focused text field

README.md

@@ -184,6 +184,9 @@ mobilecli io button --device <device-id> POWER
 # Send text
 mobilecli io text --device <device-id> 'hello world'
 
+# Replace the focused field's text in one step ('' clears it)
+mobilecli io fill --device <device-id> 'hello world'
+
 # Read device clipboard
 mobilecli io clipboard get --device <device-id>
 

agents/android/java/DeviceServer.java

@@ -141,6 +141,9 @@ private static Object dispatchMethod(UiAutomation automation, String method, JSO
 				return Input.pressKey(automation, JsonRpcSocketServer.requireParam(params, "button"), null);
 			case "device.io.keys":
 				return pressKeys(automation, p.optJSONArray("keys"));
+			case "device.io.fill":
+				// "" is a valid fill: it clears the field
+				return Input.fill(automation, JsonRpcSocketServer.requireStringParam(params, "text"));
 			case "device.io.text":
 				return Input.typeText(automation, JsonRpcSocketServer.requireParam(params, "text"));
 			case "device.clipboard.get":

agents/android/java/Input.java

@@ -1,6 +1,9 @@
 package com.mobilenext.mobilecli;
 
 import android.app.UiAutomation;
+import android.os.Bundle;
+import android.view.accessibility.AccessibilityNodeInfo;
+import android.view.accessibility.AccessibilityWindowInfo;
 import android.os.SystemClock;
 import android.view.InputDevice;
 import android.view.KeyCharacterMap;
@@ -45,6 +48,70 @@ private static JSONArray oneFinger(int x1, int y1, double holdSeconds, int x2, i
 		return actions;
 	}
 
+	/**
+	 * Replaces the focused text field's text through accessibility (ACTION_SET_TEXT);
+	 * "" clears it. Keys race the field: a Compose TextField moves its cursor to the tap
+	 * a moment after focusing, which collapses a ctrl+a selection, and a backspace then
+	 * deletes one character. Setting the text also takes any unicode without the clipboard.
+	 */
+	@SuppressWarnings("deprecation") // recycle() is a no-op on API 33+, still frees pools below
+	static JSONObject fill(UiAutomation automation, String text) throws Exception {
+		// the tap that focuses the field returns before the app has moved focus to it
+		AccessibilityNodeInfo field = findFocusedEditable(automation);
+		long deadline = SystemClock.uptimeMillis() + FOCUS_TIMEOUT_MS;
+		while (field == null && SystemClock.uptimeMillis() < deadline) {
+			SystemClock.sleep(FOCUS_POLL_MS);
+			field = findFocusedEditable(automation);
+		}
+		if (field == null) {
+			throw new RpcException(RpcException.INTERNAL_ERROR, "no text field has focus");
+		}
+		try {
+			Bundle args = new Bundle();
+			args.putCharSequence(AccessibilityNodeInfo.ACTION_ARGUMENT_SET_TEXT_CHARSEQUENCE, text);
+			if (!field.performAction(AccessibilityNodeInfo.ACTION_SET_TEXT, args)) {
+				throw new RpcException(RpcException.INTERNAL_ERROR, "the focused text field can't be filled");
+			}
+		} finally {
+			field.recycle();
+		}
+		return ok();
+	}
+
+	private static final long FOCUS_TIMEOUT_MS = 2000;
+	private static final long FOCUS_POLL_MS = 50;
+
+	// findFocus(FOCUS_INPUT) answers with the hosting view for Compose, which can't
+	// take text, so look for the focused editable node itself
+	@SuppressWarnings("deprecation")
+	private static AccessibilityNodeInfo findFocusedEditable(UiAutomation automation) {
+		for (AccessibilityWindowInfo window : automation.getWindows()) {
+			AccessibilityNodeInfo root = window.getRoot();
+			window.recycle();
+			if (root == null) continue;
+			AccessibilityNodeInfo field = findFocusedEditable(root);
+			if (field != root) root.recycle();
+			if (field != null) return field;
+		}
+		return null;
+	}
+
+	// depth-first; the caller owns the node it gets back, every other node is recycled
+	@SuppressWarnings("deprecation")
+	private static AccessibilityNodeInfo findFocusedEditable(AccessibilityNodeInfo node) {
+		if (node.isFocused() && node.isEditable()) {
+			return node;
+		}
+		for (int i = 0; i < node.getChildCount(); i++) {
+			AccessibilityNodeInfo child = node.getChild(i);
+			if (child == null) continue;
+			AccessibilityNodeInfo found = findFocusedEditable(child);
+			if (found != child) child.recycle();
+			if (found != null) return found;
+		}
+		return null;
+	}
+
 	/** Presses one key with zero or more modifiers held: modifiers down, key down/up, modifiers up. */
 	static JSONObject pressKey(UiAutomation automation, String keycode, JSONArray modifiers) throws Exception {
 		int code = resolveKeycode(keycode);

agents/android/java/JsonRpcSocketServer.java

@@ -38,6 +38,15 @@ static String requireParam(JSONObject params, String key) throws RpcException {
 		}
 		return v;
 	}
+	/** Like requireParam, but "" is a valid value; only a missing or non-string one is rejected. */
+	static String requireStringParam(JSONObject params, String key) throws RpcException {
+		Object v = params == null ? null : params.opt(key);
+		if (!(v instanceof String)) {
+			throw new RpcException(RpcException.INVALID_PARAMS, "params." + key + " must be a string");
+		}
+		return (String) v;
+	}
+
 	private static final String JSONRPC_VERSION = "2.0";
 	private static final String CONTENT_LENGTH_PREFIX = "content-length:";
 

cli/io.go

@@ -146,6 +146,21 @@ Keys name physical keys and are case-insensitive: "cmd+A" is the same as "cmd+a"
 	},
 }
 
+var ioFillCmd = &cobra.Command{
+	Use:   "fill [text]",
+	Short: "Replace the text of the focused text field on a device",
+	Long:  `Replaces the text of the field that has focus on the specified device; "" clears it. Tap the field first to focus it. Unlike "io text", which types key by key, this sets the text in one step.`,
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		req := commands.FillRequest{
+			DeviceID: deviceId,
+			Text:     args[0],
+		}
+
+		return runViaDaemon("cli.io.fill", req)
+	},
+}
+
 var ioSwipeCmd = &cobra.Command{
 	Use:   "swipe [x1,y1,x2,y2]",
 	Short: "Swipe on a device screen from one point to another",
@@ -232,6 +247,7 @@ func init() {
 	ioCmd.AddCommand(ioButtonCmd)
 	ioCmd.AddCommand(ioTextCmd)
 	ioCmd.AddCommand(ioKeysCmd)
+	ioCmd.AddCommand(ioFillCmd)
 	ioCmd.AddCommand(ioSwipeCmd)
 	ioCmd.AddCommand(ioPinchCmd)
 
@@ -243,6 +259,7 @@ func init() {
 	ioButtonCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to press button on")
 	ioTextCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to send keys to")
 	ioKeysCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to press keys on")
+	ioFillCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to fill the focused text field on")
 	ioSwipeCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to swipe on")
 	ioPinchCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to pinch on")
 	ioPinchCmd.Flags().StringVar(&pinchDirection, "direction", "", "\"in\" to zoom out or \"out\" to zoom in (required)")

commands/fill.go

@@ -0,0 +1,24 @@
+package commands
+
+import "fmt"
+
+type FillRequest struct {
+	DeviceID string `json:"deviceId"`
+	Text     string `json:"text"`
+}
+
+// FillCommand replaces the focused text field's text on the specified device; "" clears it.
+func FillCommand(req FillRequest) *CommandResponse {
+	targetDevice, err := FindDeviceWithAgent(req.DeviceID)
+	if err != nil {
+		return NewErrorResponse(err)
+	}
+
+	if err := targetDevice.Fill(req.Text); err != nil {
+		return NewErrorResponse(fmt.Errorf("failed to fill text on device %s: %v", targetDevice.ID(), err))
+	}
+
+	return NewSuccessResponse(MessageResult{
+		Message: fmt.Sprintf("Filled the focused text field on device %s", targetDevice.ID()),
+	})
+}

commands/registry.go

@@ -66,6 +66,7 @@ func CLIRegistry() map[string]CLIHandler {
 		"cli.io.button":              adapt(ButtonCommand),
 		"cli.io.text":                adapt(TextCommand),
 		"cli.io.keys":                adapt(KeysCommand),
+		"cli.io.fill":                adapt(FillCommand),
 		"cli.io.swipe":               adapt(SwipeCommand),
 		"cli.io.pinch":               adapt(PinchCommand),
 		"cli.io.gesture":             adapt(GestureCommand),

devices/android.go

@@ -977,6 +977,16 @@ func (d *AndroidDevice) PressKeys(combos []KeyCombo) error {
 	return nil
 }
 
+// Fill sets the focused field's text through accessibility, not keys: a Compose
+// TextField moves its cursor to the tap a moment after focusing, which collapses
+// a ctrl+a selection.
+func (d *AndroidDevice) Fill(text string) error {
+	if _, err := d.serverRequest("device.io.fill", textParams{Text: text}); err != nil {
+		return fmt.Errorf("AndroidDevice: failed to fill text: %w", err)
+	}
+	return nil
+}
+
 // isAscii checks if text contains only ASCII characters
 func isAscii(text string) bool {
 	for _, char := range text {

devices/common.go

@@ -203,6 +203,8 @@ type ControllableDevice interface {
 	GetClipboard() (string, error)
 	SetClipboard(text string) error
 	PressKeys(combos []KeyCombo) error
+	// Fill replaces the focused text field's text; "" clears it
+	Fill(text string) error
 	PressButton(key string) error
 	LaunchApp(bundleID string, opts LaunchOptions) error
 	TerminateApp(bundleID string) error

devices/ios.go

@@ -883,6 +883,17 @@ func (d *IOSDevice) PressKeys(combos []KeyCombo) error {
 	return d.deviceKitClient.PressKeys(toWdaKeyCombos(combos))
 }
 
+// Fill presses the HID clear key, which empties the focused field in one event, then types
+func (d *IOSDevice) Fill(text string) error {
+	if err := d.PressKeys([]KeyCombo{{Key: "clear"}}); err != nil {
+		return err
+	}
+	if text == "" {
+		return nil
+	}
+	return d.SendKeys(text)
+}
+
 func (d *IOSDevice) OpenURL(url string) error {
 	return d.deviceKitClient.OpenURL(url)
 }

devices/keys.go

@@ -14,7 +14,8 @@ type KeyCombo struct {
 func toWdaKeyCombos(combos []KeyCombo) []devicekit.KeyCombo {
 	out := make([]devicekit.KeyCombo, len(combos))
 	for i, c := range combos {
-		out[i] = devicekit.KeyCombo{Key: c.Key, Modifiers: c.Modifiers}
+		// the agent rejects "modifiers": null, so a combo without modifiers sends []
+		out[i] = devicekit.KeyCombo{Key: c.Key, Modifiers: append([]string{}, c.Modifiers...)}
 	}
 	return out
 }

devices/keys_test.go

@@ -0,0 +1,19 @@
+package devices
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// The iOS agent rejects "modifiers": null, so a combo built without modifiers must send [].
+func TestToWdaKeyCombosSendsEmptyModifiersInsteadOfNull(t *testing.T) {
+	payload, err := json.Marshal(toWdaKeyCombos([]KeyCombo{{Key: "clear"}}))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := `[{"key":"clear","modifiers":[]}]`
+	if string(payload) != want {
+		t.Fatalf("toWdaKeyCombos() = %s, want %s", payload, want)
+	}
+}

devices/remote.go

@@ -181,6 +181,10 @@ func (r *RemoteDevice) PressKeys(combos []KeyCombo) error {
 	return r.fireRPC("device.io.keys", params{"keys": keys})
 }
 
+func (r *RemoteDevice) Fill(text string) error {
+	return r.fireRPC("device.io.fill", params{"text": text})
+}
+
 func (r *RemoteDevice) PressButton(key string) error {
 	return r.fireRPC("device.io.button", params{"button": key})
 }

devices/simulator.go

@@ -642,6 +642,17 @@ func (s SimulatorDevice) PressKeys(combos []KeyCombo) error {
 	return s.deviceKitClient.PressKeys(toWdaKeyCombos(combos))
 }
 
+// Fill presses the HID clear key, which empties the focused field in one event, then types
+func (s SimulatorDevice) Fill(text string) error {
+	if err := s.PressKeys([]KeyCombo{{Key: "clear"}}); err != nil {
+		return err
+	}
+	if text == "" {
+		return nil
+	}
+	return s.SendKeys(text)
+}
+
 func (s SimulatorDevice) Tap(x, y int) error {
 	return s.deviceKitClient.Tap(x, y)
 }

docs/openrpc.json

@@ -297,6 +297,36 @@
         }
       }
     },
+    {
+      "name": "device.io.fill",
+      "summary": "Fill text field",
+      "description": "Replaces the text of the focused text field; an empty string clears it. Unlike device.io.text, which types key by key, this sets the text in one step: on Android through accessibility, on iOS by clearing the field and typing",
+      "params": [
+        {
+          "name": "deviceId",
+          "description": "ID of the target device",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "text",
+          "description": "Text to put in the field, or an empty string to clear it",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "success",
+        "description": "Operation result",
+        "schema": {
+          "$ref": "#/components/schemas/SuccessResult"
+        }
+      }
+    },
     {
       "name": "device.clipboard.get",
       "summary": "Read clipboard",

docs/openrpc.md

@@ -28,6 +28,7 @@ JSON-RPC API for mobile device automation and control
 - [device.fs.rm](#devicefsrm)
 - [device.info](#deviceinfo)
 - [device.io.button](#deviceiobutton)
+- [device.io.fill](#deviceiofill)
 - [device.io.gesture](#deviceiogesture)
 - [device.io.keys](#deviceiokeys)
 - [device.io.longpress](#deviceiolongpress)
@@ -827,6 +828,40 @@ Operation result
 ```
 
 
+### device.io.fill
+
+**Fill text field**
+
+Replaces the text of the focused text field; an empty string clears it. Unlike device.io.text, which types key by key, this sets the text in one step: on Android through accessibility, on iOS by clearing the field and typing
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `deviceId` | `string` | ✓ | ID of the target device |
+| `text` | `string` | ✓ | Text to put in the field, or an empty string to clear it |
+
+#### Response
+
+**Type:** [`SuccessResult`](#successresult)
+
+Operation result
+
+#### Example Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "device.io.fill",
+  "params": {
+    "deviceId": "string",
+    "text": "string"
+  },
+  "id": 1
+}
+```
+
+
 ### device.io.gesture
 
 **Perform custom gesture**

server/dispatch.go

@@ -22,6 +22,7 @@ func GetMethodRegistry() map[string]HandlerFunc {
 		"device.io.longpress":                   handleIoLongPress,
 		"device.io.text":                        handleIoText,
 		"device.io.keys":                        handleIoKeys,
+		"device.io.fill":                        handleIoFill,
 		"device.io.button":                      handleIoButton,
 		"device.io.swipe":                       handleIoSwipe,
 		"device.io.pinch":                       handleIoPinch,