@appium/coresim 1.8.0 → 1.9.0

package/src/native/sim_device.h

@@ -2,6 +2,8 @@
 
 #import <Foundation/Foundation.h>
 
+#include <cstdint>
+
 namespace coresim {
 
 // -[SimDevice UDID] / -[SimDevice name] / -[SimDevice state] / -[SimDevice deviceType] /
@@ -19,6 +21,11 @@ id DeviceRuntime(id device);
 // privacy-permission access (see tcc_privacy.h).
 NSString* DeviceDataPath(id device);
 
+// -[SimDevice lastBootedAt] -> the current boot session's start time (nil if never booted). Used to
+// tell a guest preference file that predates this boot from one already rewritten this boot (see
+// sim_orientation.mm).
+NSDate* DeviceLastBootedAt(id device);
+
 // -[SimDevice bootWithOptions:error:]
 BOOL Boot(id device, NSDictionary* options, NSError** error);
 
@@ -64,6 +71,10 @@ NSString* Getenv(id device, NSString* name, NSError** error);
 // the same way Apple's own Simulator.app does.
 unsigned int LookupMachPort(id device, NSString* serviceName, NSError** error);
 
+// Rotates the device via a raw GSEvent mach message to SpringBoard's "PurpleWorkspacePort" (see
+// CLAUDE.md). `orientation`: 1=portrait, 2=portraitUpsideDown, 3=landscapeRight, 4=landscapeLeft.
+BOOL SetDeviceOrientation(id device, int32_t orientation, NSError** error);
+
 // -[SimDevice installApplication:withOptions:error:]
 BOOL InstallApp(id device, NSURL* appURL, NSDictionary* options, NSError** error);
 

package/src/native/sim_device.mm

@@ -1,7 +1,10 @@
 #include "sim_device.h"
 
+#import <mach/mach.h>
 #import <objc/message.h>
 
+#include <cstring>
+
 #include "objc_runtime.h"
 #include "safe_dispatch.h"
 
@@ -9,6 +12,12 @@ namespace coresim {
 
 namespace {
 
+NSString* const kOrientationErrorDomain = @"io.appium.coresim.Orientation";
+
+NSError* MakeOrientationError(NSInteger code, NSString* message) {
+  return [NSError errorWithDomain:kOrientationErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
 // Shared shapes reused across the many identical-signature getters/setters below.
 id IdGetter(id target, const std::string& selectorName) {
   RequireSelector(target, selectorName);
@@ -53,6 +62,7 @@ NSString* DeviceName(id device) { return IdGetter(device, "name"); }
 id DeviceDeviceType(id device) { return IdGetter(device, "deviceType"); }
 id DeviceRuntime(id device) { return IdGetter(device, "runtime"); }
 NSString* DeviceDataPath(id device) { return IdGetter(device, "dataPath"); }
+NSDate* DeviceLastBootedAt(id device) { return IdGetter(device, "lastBootedAt"); }
 
 unsigned long long DeviceState(id device) {
   static const std::string kSelectorName = "state";
@@ -115,6 +125,49 @@ unsigned int LookupMachPort(id device, NSString* serviceName, NSError** error) {
   });
 }
 
+BOOL SetDeviceOrientation(id device, int32_t orientation, NSError** error) {
+  NSError* lookupError = nil;
+  unsigned int purplePort = LookupMachPort(device, @"PurpleWorkspacePort", &lookupError);
+  // The port is the authoritative success signal, not the error (see LookupMachPort's own callers,
+  // e.g. sim_pasteboard.mm).
+  if (purplePort == 0) {
+    *error = lookupError ?: MakeOrientationError(1, @"PurpleWorkspacePort is not available — is the device booted?");
+    return NO;
+  }
+
+  // GSEvent wire format, undocumented (see CLAUDE.md): mach_msg_header_t + a fixed-layout event
+  // record, in a 112-byte buffer (8-byte aligned, >= the 108-byte message mach_msg sends).
+  constexpr uint32_t kGSEventTypeDeviceOrientationChanged = 50;
+  constexpr uint32_t kGSEventHostFlag = 0x20000;
+  constexpr mach_msg_id_t kGSEventMachMessageID = 0x7B;
+  constexpr mach_msg_timeout_t kSendTimeoutMs = 2000;
+
+  uint8_t buffer[112] = {0};
+  auto* header = reinterpret_cast<mach_msg_header_t*>(buffer);
+  header->msgh_bits = 0x13;  // MACH_MSGH_BITS(MACH_MSG_TYPE_COPY_SEND, 0)
+  header->msgh_size = 108;   // align4(4 + 0x6B) — matches Simulator.app's own sendPurpleEvent:
+  header->msgh_remote_port = purplePort;
+  header->msgh_local_port = MACH_PORT_NULL;
+  header->msgh_id = kGSEventMachMessageID;
+
+  uint32_t type = kGSEventTypeDeviceOrientationChanged | kGSEventHostFlag;
+  std::memcpy(buffer + 0x18, &type, sizeof(type));
+  uint32_t recordInfoSize = 4;
+  std::memcpy(buffer + 0x48, &recordInfoSize, sizeof(recordInfoSize));
+  uint32_t orientationValue = static_cast<uint32_t>(orientation);
+  std::memcpy(buffer + 0x4C, &orientationValue, sizeof(orientationValue));
+
+  kern_return_t kr = mach_msg(header, MACH_SEND_MSG | MACH_SEND_TIMEOUT, header->msgh_size, 0, MACH_PORT_NULL,
+                              kSendTimeoutMs, MACH_PORT_NULL);
+  if (kr != KERN_SUCCESS) {
+    *error = MakeOrientationError(
+        2, [NSString stringWithFormat:@"Failed to send the orientation change (kern_return_t %d): %s", kr,
+                                      mach_error_string(kr)]);
+    return NO;
+  }
+  return YES;
+}
+
 BOOL InstallApp(id device, NSURL* appURL, NSDictionary* options, NSError** error) {
   static const std::string kSelectorName = "installApplication:withOptions:error:";
   RequireSelector(device, kSelectorName);

package/src/native/sim_orientation.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <cstdint>
+
+namespace coresim {
+
+// A live orientation read straight off backboardd's own persisted preference file on the host side
+// (see CLAUDE.md) — reflects a rotation from any source, not just this process's own
+// SetDeviceOrientation calls. Calls `handler` once, async, with a DeviceOrientation wire value
+// (types.ts) — always 1 (portrait) if the device hasn't rotated yet this boot, or on any read
+// failure.
+void ReadGuestOrientation(id device, void (^handler)(int32_t orientation));
+
+}  // namespace coresim

package/src/native/sim_orientation.mm

@@ -0,0 +1,58 @@
+#include "sim_orientation.h"
+
+#include "sim_device.h"
+
+namespace coresim {
+
+namespace {
+
+// backboardd's persisted GraphicsOrientation swaps landscape left/right vs. our own
+// DeviceOrientation wire values — confirmed empirically (see CLAUDE.md).
+int32_t TranslateGraphicsOrientation(NSInteger graphicsOrientation) {
+  switch (graphicsOrientation) {
+    case 3:
+      return 4;
+    case 4:
+      return 3;
+    default:
+      return static_cast<int32_t>(graphicsOrientation);
+  }
+}
+
+// The live digitizer entry for the current boot, or nil if it hasn't rotated yet this boot (or
+// `plist` is nil/malformed). Reading straight from the file (a real binary plist) gives properly
+// typed values — no ASCII-vs-binary parsing ambiguity to handle.
+NSNumber* CurrentGraphicsOrientation(NSDictionary* plist) {
+  NSArray* entries = [plist[@"BKDigitizerPersistentServiceProperties"] isKindOfClass:[NSArray class]]
+                         ? plist[@"BKDigitizerPersistentServiceProperties"]
+                         : nil;
+  NSDictionary* last = [entries.lastObject isKindOfClass:[NSDictionary class]] ? entries.lastObject : nil;
+  NSDictionary* props = [last[@"props"] isKindOfClass:[NSDictionary class]] ? last[@"props"] : nil;
+  return [props[@"GraphicsOrientation"] isKindOfClass:[NSNumber class]] ? props[@"GraphicsOrientation"] : nil;
+}
+
+}  // namespace
+
+void ReadGuestOrientation(id device, void (^handler)(int32_t orientation)) {
+  NSString* plistPath =
+      [DeviceDataPath(device) stringByAppendingPathComponent:@"Library/Preferences/com.apple.backboardd.plist"];
+  NSDate* lastBootedAt = DeviceLastBootedAt(device);
+
+  dispatch_async(dispatch_get_global_queue(QOS_CLASS_UTILITY, 0), ^{
+    NSDate* modified = [[NSFileManager defaultManager] attributesOfItemAtPath:plistPath
+                                                                        error:nil][NSFileModificationDate];
+    // The whole file predates this boot, so none of its entries — including the last one — can
+    // belong to it (confirmed empirically: a reboot leaves the previous boot's entry in place until
+    // backboardd rewrites the file, sometimes several seconds after boot completes — see CLAUDE.md).
+    // Treat exactly like "never rotated this boot" rather than trusting stale content.
+    if (lastBootedAt != nil && modified != nil && [modified compare:lastBootedAt] == NSOrderedAscending) {
+      handler(1);
+      return;
+    }
+    NSDictionary* plist = [NSDictionary dictionaryWithContentsOfFile:plistPath];
+    NSNumber* graphicsOrientation = CurrentGraphicsOrientation(plist);
+    handler(graphicsOrientation != nil ? TranslateGraphicsOrientation(graphicsOrientation.integerValue) : 1);
+  });
+}
+
+}  // namespace coresim

package/src/native/sim_screenshot.h

@@ -18,6 +18,11 @@ NSArray<NSDictionary*>* ListDisplays(id device, NSError** error);
 // object itself (e.g. StartVideoRecording's `screen` argument).
 id ResolveCaptureDisplay(id device, NSString* displayId, NSError** error);
 
+// The device-wide "capture service" port (real protocol: SimScreenCaptureService — see CLAUDE.md),
+// distinct from a display descriptor (see ResolveCaptureDisplay above). Found by scanning ioPorts
+// since no header exists. Throws NativeSimUnavailableError (not NSError**) if absent.
+id ResolveScreenCaptureService(id device, NSError** error);
+
 // The descriptor's current framebuffer as an `IOSurfaceRef` (bridge-cast the returned `id`).
 // Returns nil if not available yet (e.g. connection just dropped) — not an error, since that can
 // legitimately happen from one call to the next on a live device.

package/src/native/sim_screenshot.mm

@@ -152,6 +152,27 @@ id ResolveCaptureDisplay(id device, NSString* displayId, NSError** error) {
   return ResolveDisplayDescriptor(candidates, displayId, error);
 }
 
+// The real protocol is SimScreenCaptureService (see CLAUDE.md) — found by scanning ioPorts for
+// whichever descriptor responds to startRecordingFromScreen:..., since no header exists for it.
+id ResolveScreenCaptureService(id device, NSError** error) {
+  static const std::string kStartRecordingSelector =
+      "startRecordingFromScreen:maskPolicy:assetWriterOutputSettings:outputFile:completionQueue:completionHandler:";
+  id ioClient = IdGetter(device, "io");
+  if (ioClient == nil) {
+    *error = MakeError(11, @"Device has no IO client available — is it booted?");
+    return nil;
+  }
+  NSArray* ports = IdGetter(ioClient, "ioPorts");
+  SEL selector = NSSelectorFromString(@(kStartRecordingSelector.c_str()));
+  for (id port in ports) {
+    id descriptor = IdGetter(port, "descriptor");
+    if (descriptor != nil && [descriptor respondsToSelector:selector]) {
+      return descriptor;
+    }
+  }
+  throw NativeSimUnavailableError("selector", kStartRecordingSelector, CoreSimulatorFrameworkVersion());
+}
+
 id CurrentDisplaySurface(id descriptor) { return RenderableSurface(descriptor); }
 
 NSArray<NSDictionary*>* ListDisplays(id device, NSError** error) {

package/src/native/sim_video_recording.mm

@@ -8,50 +8,9 @@
 
 namespace coresim {
 
-namespace {
-
-NSString* const kVideoRecordingErrorDomain = @"io.appium.coresim.VideoRecording";
-
-NSError* MakeError(NSInteger code, NSString* message) {
-  return [NSError errorWithDomain:kVideoRecordingErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
-}
-
-id IdGetter(id target, const std::string& selectorName) {
-  RequireSelector(target, selectorName);
-  SEL selector = SelectorNamed(selectorName);
-  return SafeInvoke([&] {
-    using Fn = id (*)(id, SEL);
-    return ((Fn)objc_msgSend)(target, selector);
-  });
-}
-
-// The device-wide "capture service" port (real protocol: SimScreenCaptureService — see CLAUDE.md),
-// distinct from the display descriptor passed as `screen` below. Found by scanning ioPorts since
-// no header exists. Throws NativeSimUnavailableError (not NSError**) if absent.
-id ResolveVideoCaptureService(id device, NSError** error) {
-  static const std::string kStartRecordingSelector =
-      "startRecordingFromScreen:maskPolicy:assetWriterOutputSettings:outputFile:completionQueue:completionHandler:";
-  id ioClient = IdGetter(device, "io");
-  if (ioClient == nil) {
-    *error = MakeError(1, @"Device has no IO client available — is it booted?");
-    return nil;
-  }
-  NSArray* ports = IdGetter(ioClient, "ioPorts");
-  SEL selector = NSSelectorFromString(@(kStartRecordingSelector.c_str()));
-  for (id port in ports) {
-    id descriptor = IdGetter(port, "descriptor");
-    if (descriptor != nil && [descriptor respondsToSelector:selector]) {
-      return descriptor;
-    }
-  }
-  throw NativeSimUnavailableError("selector", kStartRecordingSelector, CoreSimulatorFrameworkVersion());
-}
-
-}  // namespace
-
 BOOL StartVideoRecording(id device, NSString* displayId, VideoMaskPolicy mask, NSDictionary* assetWriterOutputSettings,
                          NSString* outputFile, dispatch_queue_t queue, void (^handler)(NSError*), NSError** error) {
-  id captureService = ResolveVideoCaptureService(device, error);
+  id captureService = ResolveScreenCaptureService(device, error);
   if (captureService == nil) {
     return NO;
   }
@@ -71,7 +30,7 @@ BOOL StartVideoRecording(id device, NSString* displayId, VideoMaskPolicy mask, N
 }
 
 BOOL StopVideoRecording(id device, dispatch_queue_t queue, void (^handler)(NSError*), NSError** error) {
-  id captureService = ResolveVideoCaptureService(device, error);
+  id captureService = ResolveScreenCaptureService(device, error);
   if (captureService == nil) {
     return NO;
   }

package/src/native/video_encoder.h

@@ -17,6 +17,13 @@ struct VideoEncoderOptions {
   NSString* displayId = nil;
   double fps = 60.0;
   int bitrate = 4000000;
+
+  // Freezes the encoded frame size at whatever it is on the first frame, forever — a rotation
+  // afterward letterboxes into that size instead of resizing the session to match. Internal-only
+  // (not JS-configurable): AVRecordingSession forces this on, since its AVAssetWriter track's
+  // dimensions are fixed for the file's life (see CLAUDE.md); a live stream has no such constraint
+  // and keeps the default (false), matching its own decoded dimensions to the actual rotation.
+  bool fixedFrameSize = false;
 };
 
 // Polls the live display IOSurface (sim_screenshot.h) on a serial queue and encodes changed