@stim-cli/server 1.11.0 → 1.12.0

package/dist/protocol.schema.json

@@ -32,7 +32,9 @@
             "forbidden",
             "unknown-action",
             "action-busy",
-            "action-failed"
+            "action-failed",
+            "device-busy",
+            "unknown-session"
           ]
         },
         "message": {
@@ -232,10 +234,11 @@
         },
         "slot": {
           "type": "string",
-          "minLength": 1
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
         },
         "grep": {
           "type": "string",
+          "pattern": "^[^\\u0000]*$",
           "description": "A regular expression matched against each message."
         },
         "errors": {
@@ -363,6 +366,95 @@
         }
       }
     },
+    "ControlBeginParams": {
+      "type": "object",
+      "required": [
+        "workspace",
+        "platform"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "workspace": {
+          "type": "string",
+          "description": "An environment path from a status payload."
+        },
+        "platform": {
+          "enum": [
+            "ios",
+            "android"
+          ]
+        },
+        "slot": {
+          "type": "string",
+          "minLength": 1,
+          "default": "default"
+        },
+        "takeOver": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
+    "ControlBeginResult": {
+      "type": "object",
+      "required": [
+        "session",
+        "platform",
+        "lease",
+        "postures"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "session": {
+          "type": "string"
+        },
+        "platform": {
+          "enum": [
+            "ios",
+            "android"
+          ]
+        },
+        "lease": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "grantedAt",
+                "expiresAt"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "grantedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "format": "date-time"
+                },
+                "expiresAt": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              }
+            }
+          ]
+        },
+        "postures": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "folded",
+              "half-open",
+              "unfolded"
+            ]
+          },
+          "uniqueItems": true
+        }
+      }
+    },
     "BuildPlanParams": {
       "type": "object",
       "required": [
@@ -895,6 +987,278 @@
               "$ref": "#/$defs/ActionParams"
             }
           }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "control.begin"
+            },
+            "params": {
+              "$ref": "#/$defs/ControlBeginParams"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "control.end"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "input.touch"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session",
+                "phase",
+                "x",
+                "y"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                },
+                "phase": {
+                  "enum": [
+                    "down",
+                    "move",
+                    "up"
+                  ]
+                },
+                "x": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                },
+                "y": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                },
+                "display": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 3,
+                  "default": 0
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "input.text"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session",
+                "text"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                },
+                "text": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 256,
+                  "pattern": "^[\\x20-\\x7e\\n\\t\\b]+$"
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "input.button"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session",
+                "button"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                },
+                "button": {
+                  "enum": [
+                    "home",
+                    "lock",
+                    "back",
+                    "app-switch"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "input.rotate"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session",
+                "direction"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                },
+                "direction": {
+                  "enum": [
+                    "left",
+                    "right"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "input.posture"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "session",
+                "posture"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "session": {
+                  "type": "string"
+                },
+                "posture": {
+                  "enum": [
+                    "folded",
+                    "half-open",
+                    "unfolded"
+                  ]
+                }
+              }
+            }
+          }
         }
       ]
     },
@@ -919,6 +1283,9 @@
                 {
                   "$ref": "#/$defs/HelloResult"
                 },
+                {
+                  "$ref": "#/$defs/ControlBeginResult"
+                },
                 {
                   "$ref": "#/$defs/ActionResult"
                 },
@@ -1111,6 +1478,36 @@
             }
           }
         },
+        {
+          "type": "object",
+          "required": [
+            "event",
+            "session",
+            "reason",
+            "message"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "event": {
+              "const": "control-ended"
+            },
+            "session": {
+              "type": "string"
+            },
+            "reason": {
+              "enum": [
+                "idle",
+                "taken-over",
+                "device-gone",
+                "forbidden",
+                "failed"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
         {
           "type": "object",
           "required": [

package/dist/stim-frames/EmulatorPosture.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// The posture of a foldable emulator, as the emulator's Posture.PostureValue
+/// numbers it.
+public enum EmulatorPosture: Int, CaseIterable, Sendable {
+  case closed = 1
+  case halfOpened = 2
+  case opened = 3
+  case flipped = 4
+  case tent = 5
+
+  public var label: String {
+    switch self {
+    case .closed: return "Folded"
+    case .halfOpened: return "Half open"
+    case .opened: return "Unfolded"
+    case .flipped: return "Flipped"
+    case .tent: return "Tent"
+    }
+  }
+
+  /// The emulator's current posture; nil for an emulator without a hinge, or
+  /// one whose endpoint cannot be reached.
+  public static func current(serial: String) async -> EmulatorPosture? {
+    guard let endpoint = EmulatorDiscovery.endpoint(serial: serial) else { return nil }
+    let input = EmulatorInput(endpoint: endpoint)
+    defer { input.close() }
+    return await input.call("getPhysicalModel", PostureMessages.postureTarget).flatMap(PostureMessages.posture)
+  }
+
+  /// Moves the hinge to this posture. Returns false when the emulator has no
+  /// endpoint or refuses the call.
+  public func apply(serial: String) async -> Bool {
+    guard let endpoint = EmulatorDiscovery.endpoint(serial: serial) else { return false }
+    let input = EmulatorInput(endpoint: endpoint)
+    defer { input.close() }
+    return await input.call("setPosture", PostureMessages.setPosture(self)) != nil
+  }
+}
+
+// Field numbers follow PhysicalModelValue, ParameterValue and Posture in the
+// emulator's emulator_controller.proto (sdk/emulator/lib); POSTURE is
+// PhysicalType 16, and its single value is the PostureValue as a float.
+enum PostureMessages {
+  static let postureTarget = Data([0x08, 0x10])
+
+  static func setPosture(_ posture: EmulatorPosture) -> Data {
+    Data([0x18, UInt8(posture.rawValue)])
+  }
+
+  static func posture(fromPhysicalModel bytes: Data) -> EmulatorPosture? {
+    var reader = ProtoReader(bytes)
+    while let (field, value) = reader.next() {
+      if field == 2, case .varint(let status) = value, status != 0 { return nil }
+      guard field == 3, case .bytes(let parameter) = value else { continue }
+      var values = ProtoReader(parameter)
+      while let (valueField, packed) = values.next() {
+        guard valueField == 1, case .bytes(let data) = packed, data.count >= 4 else { continue }
+        let raw = Float(bitPattern: data.prefix(4).reversed().reduce(0) { $0 << 8 | UInt32($1) })
+        return EmulatorPosture(rawValue: Int(raw.rounded()))
+      }
+    }
+    return nil
+  }
+}
+
+extension EmulatorInput {
+  func call(_ method: String, _ message: Data) async -> Data? {
+    await withCheckedContinuation { continuation in
+      call(method, message) { continuation.resume(returning: $0) }
+    }
+  }
+}

package/dist/stim-frames/EmulatorRotation.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// Turns a running emulator a quarter turn through its gRPC endpoint. It sets
+/// the z angle of the ROTATION physical model, as turning a real device would,
+/// so the screen follows the app's and the system's rotation rules; with
+/// auto-rotate off, Android offers its rotate suggestion instead.
+public enum EmulatorRotation {
+  /// Returns false when the emulator has no endpoint or refuses the call.
+  public static func rotate(serial: String, clockwise: Bool) async -> Bool {
+    guard let endpoint = EmulatorDiscovery.endpoint(serial: serial) else { return false }
+    let input = EmulatorInput(endpoint: endpoint)
+    defer { input.close() }
+    guard let current = await input.call("getPhysicalModel", RotationMessages.rotationTarget) else { return false }
+    let angles = RotationMessages.angles(fromPhysicalModel: current)
+    let turned = RotationMessages.quarterTurn(z: angles.z, clockwise: clockwise)
+    let message = RotationMessages.rotation(x: angles.x, y: angles.y, z: turned)
+    return await input.call("setPhysicalModel", message) != nil
+  }
+}
+
+// Field numbers follow PhysicalModelValue and ParameterValue in the emulator's
+// emulator_controller.proto (sdk/emulator/lib); ROTATION is PhysicalType 1 and
+// its values are x, y and z angles in degrees.
+enum RotationMessages {
+  static let rotationTarget = Data([0x08, 0x01])
+
+  static func rotation(x: Float, y: Float, z: Float) -> Data {
+    var floats = Data()
+    for value in [x, y, z] { withUnsafeBytes(of: value.bitPattern.littleEndian) { floats += $0 } }
+    let parameter = Data([0x0a, UInt8(floats.count)]) + floats
+    return rotationTarget + Data([0x1a, UInt8(parameter.count)]) + parameter
+  }
+
+  /// The angles in a PhysicalModelValue; proto3 omits an all-zero value.
+  static func angles(fromPhysicalModel bytes: Data) -> (x: Float, y: Float, z: Float) {
+    var reader = ProtoReader(bytes)
+    while let (field, value) = reader.next() {
+      guard field == 3, case .bytes(let parameter) = value else { continue }
+      var values = ProtoReader(parameter)
+      while let (valueField, packed) = values.next() {
+        guard valueField == 1, case .bytes(let data) = packed, data.count >= 12 else { continue }
+        let floats = stride(from: 0, to: 12, by: 4).map { offset in
+          Float(bitPattern: data.dropFirst(offset).prefix(4).reversed().reduce(0) { $0 << 8 | UInt32($1) })
+        }
+        return (floats[0], floats[1], floats[2])
+      }
+    }
+    return (0, 0, 0)
+  }
+
+  /// The next z angle, in (-180, 180]; a positive angle turns the device counterclockwise.
+  static func quarterTurn(z: Float, clockwise: Bool) -> Float {
+    let quarter = (z / 90).rounded() * 90
+    var next = quarter + (clockwise ? -90 : 90)
+    if next > 180 { next -= 360 }
+    if next <= -180 { next += 360 }
+    return next
+  }
+}

package/dist/stim-frames/InputMessages.swift

@@ -5,6 +5,7 @@ import Foundation
 enum InputMessages {
   static let macKeyCodeType: UInt64 = 4
   static let keyup: UInt64 = 1
+  static let keypress: UInt64 = 2
 
   /// A MouseEvent on the main display. `pressed` sets the primary button; the
   /// emulator turns it into a single touch on a touchscreen device.
@@ -12,6 +13,20 @@ enum InputMessages {
     message([(1, UInt64(max(x, 0))), (2, UInt64(max(y, 0))), (3, pressed ? 1 : 0)])
   }
 
+  /// A TouchEvent with one finger on the main display, lifted when `pressed`
+  /// is false (pressure 0). Unlike a MouseEvent, Android sees a touchscreen
+  /// finger, not a mouse or stylus.
+  static func touch(x: Int, y: Int, pressed: Bool) -> Data {
+    var touch = Data()
+    for (field, value) in [(1, UInt64(max(x, 0))), (2, UInt64(max(y, 0))), (4, pressed ? 1 : 0)] where value != 0 {
+      ScreenshotMessages.appendVarint(UInt64(field << 3), to: &touch)
+      ScreenshotMessages.appendVarint(value, to: &touch)
+    }
+    var out = Data()
+    appendBytes(field: 1, touch, to: &out)
+    return out
+  }
+
   /// A KeyboardEvent the emulator types as a key press per character.
   static func text(_ text: String) -> Data {
     var out = Data()
@@ -25,23 +40,42 @@ enum InputMessages {
     message([(1, macKeyCodeType), (2, down ? 0 : keyup), (3, UInt64(macKeyCode))])
   }
 
+  /// A KeyboardEvent that presses and releases the key a DOM key name such as
+  /// `GoHome` or `Power` names.
+  static func namedKey(_ key: String) -> Data {
+    var out = message([(2, keypress)])
+    appendBytes(field: 4, Data(key.utf8), to: &out)
+    return out
+  }
+
   /// The main display's size in pixels, read from `hw.lcd.width` and
   /// `hw.lcd.height` in an EmulatorStatus's hardwareConfig.
   static func displaySize(fromStatus bytes: Data) -> (width: Int, height: Int)? {
+    let config = hardwareConfig(fromStatus: bytes)
+    guard let width = config["hw.lcd.width"].flatMap({ Int($0) }), let height = config["hw.lcd.height"].flatMap({ Int($0) }),
+      width > 0, height > 0
+    else { return nil }
+    return (width, height)
+  }
+
+  /// Whether the emulator has a hardware keyboard (`hw.keyboard` in an
+  /// EmulatorStatus's hardwareConfig). Without one it drops every KeyboardEvent.
+  static func hasKeyboard(fromStatus bytes: Data) -> Bool {
+    hardwareConfig(fromStatus: bytes)["hw.keyboard"] == "true"
+  }
+
+  private static func hardwareConfig(fromStatus bytes: Data) -> [String: String] {
     var reader = ProtoReader(bytes)
-    var width: Int?
-    var height: Int?
+    var config: [String: String] = [:]
     while let (field, value) = reader.next() {
       guard field == 5, case .bytes(let list) = value else { continue }
       var entries = ProtoReader(list)
       while let (entryField, entryValue) = entries.next() {
         guard entryField == 1, case .bytes(let entry) = entryValue, let (key, value) = pair(entry) else { continue }
-        if key == "hw.lcd.width" { width = Int(value) }
-        if key == "hw.lcd.height" { height = Int(value) }
+        config[key] = value
       }
     }
-    guard let width, let height, width > 0, height > 0 else { return nil }
-    return (width, height)
+    return config
   }
 
   private static func pair(_ bytes: Data) -> (String, String)? {
@@ -71,3 +105,19 @@ enum InputMessages {
     out += bytes
   }
 }
+
+/// Maps a fraction of the upright image, origin top-left, to a pixel of the
+/// display in its native orientation, which is where the emulator places
+/// touches. `rotation` is the image's Rotation.SkinRotation.
+func displayPixel(_ point: CGPoint, rotation: Int, displaySize: CGSize) -> (x: Int, y: Int) {
+  let native: CGPoint
+  switch rotation {
+  case 1: native = CGPoint(x: 1 - point.y, y: point.x)
+  case 2: native = CGPoint(x: 1 - point.x, y: 1 - point.y)
+  case 3: native = CGPoint(x: point.y, y: 1 - point.x)
+  default: native = point
+  }
+  let x = Int((native.x * displaySize.width).rounded(.down))
+  let y = Int((native.y * displaySize.height).rounded(.down))
+  return (min(max(x, 0), Int(displaySize.width) - 1), min(max(y, 0), Int(displaySize.height) - 1))
+}