@appium/coresim 1.7.0 → 1.9.0

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_jpeg_stream.h

@@ -0,0 +1,69 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <vector>
+
+namespace coresim {
+
+struct JpegStreamOptions {
+  NSString* displayId = nil;
+  double fps = 60.0;
+  // 0-100 percent; same semantics as CaptureScreenshot's jpegQualityPercent (sim_screenshot.h),
+  // nil-able for ImageIO's own default (near-lossless, so a much larger frame) — but defaulted to
+  // 80 by coresim.mm rather than left nil, since a continuous live stream should default to
+  // noticeably smaller frames, unlike a one-off CaptureScreenshot call.
+  NSNumber* jpegQualityPercent = @80;
+  // 0.0-1.0 fraction of the original frame's width/height; 1.0 (default) performs no scaling.
+  // Already normalized from the JS-facing 1-100 percent option by coresim.mm.
+  double scale = 1.0;
+};
+
+// One JPEG-encoded frame. Unlike VideoAccessUnit, every frame is independently decodable — there's
+// no keyframe/interframe distinction, so no resync semantics are needed on the consuming side.
+struct JpegFrame {
+  std::vector<uint8_t> data;
+  uint64_t sequence = 0;
+  // Microseconds since the stream started.
+  int64_t timestampMicros = 0;
+};
+
+// Polls the live display IOSurface (sim_screenshot.h) on a serial queue and JPEG-encodes changed
+// frames via ImageIO, delivering each live — see CLAUDE.md for how this relates to
+// VideoStreamSession and CaptureScreenshot.
+class JpegStreamSession {
+ public:
+  // `onAbortDelivery`, if set, is invoked by AbortDelivery() below — not called by this class on
+  // its own.
+  JpegStreamSession(id device, JpegStreamOptions options, std::function<void(JpegFrame)> onFrame,
+                    std::function<void(NSError*)> onError, std::function<void()> onEnd,
+                    std::function<void()> onAbortDelivery = nullptr);
+  ~JpegStreamSession();
+
+  JpegStreamSession(const JpegStreamSession&) = delete;
+  JpegStreamSession& operator=(const JpegStreamSession&) = delete;
+
+  // Resolves the display and starts the polling loop; throws synchronously on resolution/setup
+  // failure (`onEnd` never called then). Later failures go to `onError`, then `onEnd`.
+  void Start();
+
+  // Idempotent; blocks until the loop has fully stopped. Never call from inside onFrame/onError/
+  // onEnd — same queue this blocks on, so it would deadlock.
+  void Stop();
+
+  // Runs the constructor's `onAbortDelivery` (if any) — e.g. aborting a bounded delivery queue so
+  // a producer thread blocked pushing into it unblocks. Call before Stop() when the caller can't
+  // rely on anything else draining that queue concurrently (e.g. process-exit cleanup running
+  // synchronously on the same thread `Stop()` would otherwise wait on) — a normal Stop() doesn't
+  // need this. Safe from any thread; a no-op if unset.
+  void AbortDelivery();
+
+ private:
+  class Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+}  // namespace coresim

package/src/native/sim_jpeg_stream.mm

@@ -0,0 +1,322 @@
+#include "sim_jpeg_stream.h"
+
+#import <CoreImage/CoreImage.h>
+#import <IOSurface/IOSurface.h>
+
+#include <algorithm>
+#include <atomic>
+#include <cmath>
+
+#include "monotonic_clock.h"
+#include "nserror_bridge.h"
+#include "sim_screenshot.h"
+
+namespace coresim {
+
+namespace {
+
+NSString* const kJpegStreamErrorDomain = @"io.appium.coresim.JpegStream";
+
+// A scale this close to 1.0 (from a 1-100 percent option divided by 100.0 — never exactly 1.0
+// except at 100%) is treated as "no scaling" — comparing doubles for exact equality is unreliable.
+constexpr double kScaleEpsilon = 1e-9;
+
+// If no frame can be produced for this long — the display surface staying unavailable, or the
+// CIImage/CGImage render failing — for that whole stretch, something is genuinely wrong (a
+// permanently dropped connection, say) rather than a one-off transient hiccup; escalate to a real
+// error instead of polling forever with nothing to show for it and no error ever reported.
+constexpr double kMaxStallSeconds = 10.0;
+
+NSError* MakeError(NSInteger code, NSString* message) {
+  return [NSError errorWithDomain:kJpegStreamErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
+}  // namespace
+
+class JpegStreamSession::Impl {
+ public:
+  Impl(id device, JpegStreamOptions options, std::function<void(JpegFrame)> onFrame,
+       std::function<void(NSError*)> onError, std::function<void()> onEnd, std::function<void()> onAbortDelivery)
+      : device_(device),
+        options_(options),
+        onFrame_(std::move(onFrame)),
+        onError_(std::move(onError)),
+        onEnd_(std::move(onEnd)),
+        onAbortDelivery_(std::move(onAbortDelivery)) {
+    queue_ = dispatch_queue_create("io.appium.coresim.jpegStream", DISPATCH_QUEUE_SERIAL);
+    // Persistent, unlike CaptureScreenshot's own one-shot CIContext (see sim_screenshot.mm) — that
+    // file's comment calls this out as exactly the tradeoff a continuous streaming path should
+    // make instead.
+    context_ = [CIContext contextWithOptions:nil];
+  }
+
+  ~Impl() { Stop(); }
+
+  void Start() {
+    NSError* error = nil;
+    id descriptor = ResolveCaptureDisplay(device_, options_.displayId, &error);
+    if (descriptor == nil) {
+      throw NSErrorException(error);
+    }
+    id surfaceObj = CurrentDisplaySurface(descriptor);
+    if (surfaceObj == nil) {
+      throw NSErrorException(MakeError(1, @"The device's display surface is not available yet"));
+    }
+    IOSurfaceRef surface = (__bridge IOSurfaceRef)surfaceObj;
+
+    startTime_ = MonotonicSeconds();
+    // Set before the initial encode below — EmitFrame measures elapsed time from it, and running_
+    // gates whether a frame is delivered at all (see Tick()'s own check).
+    running_ = true;
+    // Encode immediately rather than waiting for a *changed* seed on the first tick, or the stream
+    // would stay silent until the display changes again — unlike Tick(), this doesn't check
+    // lastSeed_ first (it's still its default 0), so EncodeCurrentSeedAndEmit always runs once here.
+    NSError* encodeError = nil;
+    EncodeCurrentSeedAndEmit(surface, &encodeError);
+    if (encodeError != nil) {
+      running_ = false;
+      throw NSErrorException(encodeError);
+    }
+
+    double interval = 1.0 / std::max(options_.fps, 1.0);
+    dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, queue_);
+    dispatch_source_set_timer(timer, dispatch_time(DISPATCH_TIME_NOW, 0),
+                              static_cast<uint64_t>(interval * NSEC_PER_SEC),
+                              static_cast<uint64_t>(interval * NSEC_PER_SEC / 10));
+    // `this` outlives the timer: Stop()/StopFromQueue() always cancel or outrun it before `this`
+    // can be destroyed (see their comments below).
+    dispatch_source_set_event_handler(timer, ^{
+      Tick();
+    });
+    timer_ = timer;
+    dispatch_resume(timer_);
+  }
+
+  // Callable from any thread except `queue_` itself (would deadlock on the dispatch_sync below).
+  void Stop() {
+    if (!running_.exchange(false)) {
+      return;  // idempotent
+    }
+    if (timer_ != nullptr) {
+      dispatch_source_cancel(timer_);
+      // dispatch_source_cancel doesn't preempt a currently-executing handler — an already-running
+      // Tick() (past its own `running_` check) can still run to completion and emit one last frame
+      // via onFrame_ before this returns. This blocks until that happens, so onEnd_ below (which
+      // the caller uses to release resources onFrame_ needs, e.g. a ThreadSafeFunction) never races
+      // a still-in-flight emit — not, as such, a guarantee that no further frame is ever emitted.
+      dispatch_sync(queue_, ^{
+                    });
+      timer_ = nullptr;
+    }
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  void AbortDelivery() {
+    if (onAbortDelivery_) {
+      onAbortDelivery_();
+    }
+  }
+
+ private:
+  // Same as Stop() minus the dispatch_sync barrier — only safe from within Tick() itself, already
+  // serialized on `queue_`; would race a concurrent Tick() from any other thread.
+  void StopFromQueue() {
+    if (!running_.exchange(false)) {
+      return;  // idempotent — e.g. an external Stop() already won this race
+    }
+    if (timer_ != nullptr) {
+      dispatch_source_cancel(timer_);
+      timer_ = nullptr;
+    }
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  void Tick() {
+    if (!running_) {
+      return;
+    }
+    @autoreleasepool {
+      try {
+        // Re-resolved every tick (like CaptureScreenshot does), not cached once in Start(), so a
+        // deleted device or disconnected display surfaces a real error instead of Tick() quietly
+        // doing nothing forever.
+        NSError* resolveError = nil;
+        id descriptor = ResolveCaptureDisplay(device_, options_.displayId, &resolveError);
+        if (descriptor == nil) {
+          if (onError_) {
+            onError_(resolveError);
+          }
+          StopFromQueue();
+          return;
+        }
+        id surfaceObj = CurrentDisplaySurface(descriptor);
+        if (surfaceObj == nil) {
+          ReportIfStalledTooLong();  // transient — the connection may not have a frame ready yet
+          return;
+        }
+        IOSurfaceRef surface = (__bridge IOSurfaceRef)surfaceObj;
+        uint32_t seed = IOSurfaceGetSeed(surface);
+        if (seed == lastSeed_) {
+          // Unchanged since the last tick (mirrors VideoFrameEncoder's own seed check) — the
+          // surface itself is fine, just nothing new to encode, so this resolves any stall.
+          stalledSince_ = 0;
+          return;
+        }
+        NSError* encodeError = nil;
+        bool encoded = EncodeCurrentSeedAndEmit(surface, &encodeError);
+        if (encodeError != nil) {
+          if (onError_) {
+            onError_(encodeError);
+          }
+          StopFromQueue();
+          return;
+        }
+        if (encoded) {
+          stalledSince_ = 0;
+        } else {
+          ReportIfStalledTooLong();  // transient — e.g. a momentary CIImage/CGImage render failure
+        }
+      } catch (const std::exception& e) {
+        // Without this, an exception here (e.g. a dropped display-proxy connection, which surfaces
+        // as NativeSimUnavailableError/ObjCException — both std::exception subtypes — via
+        // ResolveCaptureDisplay's own dynamic dispatch) would escape this bare GCD timer handler
+        // uncaught and crash the whole process (see CLAUDE.md; mirrors VideoFrameEncoder::Tick()).
+        if (onError_) {
+          onError_(MakeError(4, [NSString stringWithFormat:@"JPEG streaming failed: %s", e.what()]));
+        }
+        StopFromQueue();
+      }
+    }
+  }
+
+  // Called from Tick() on a tick that produced nothing but also wasn't a genuine (reported) error —
+  // starts a stall timer on the first such tick, and escalates to a real onError_/StopFromQueue()
+  // once it's run past kMaxStallSeconds without a single successful tick (a frame, or an unchanged-
+  // seed check) in between. Without this, a display surface that never comes back (or a
+  // CIImage/CGImage render that never succeeds again) would poll forever with nothing to show for
+  // it and no error ever reported (see CLAUDE.md).
+  void ReportIfStalledTooLong() {
+    double now = MonotonicSeconds();
+    if (stalledSince_ == 0) {
+      stalledSince_ = now;
+      return;
+    }
+    if (now - stalledSince_ > kMaxStallSeconds) {
+      if (onError_) {
+        onError_(MakeError(5, @"No JPEG frame could be produced for too long"));
+      }
+      StopFromQueue();
+    }
+  }
+
+  // Reads `surface`'s current seed, attempts one encode, and — only on success — commits exactly
+  // that pre-encode seed to lastSeed_ and emits the frame. Reading the seed before encoding (never
+  // a value re-read afterward) matters: if the display changes again while EncodeSurface() is still
+  // running, the pre-encode seed still correctly identifies which content this frame captures, so
+  // the next caller sees the surface's now-newer seed as "changed" and retries — reading it after
+  // encoding instead would wrongly commit the *newer* seed against the *older* frame just emitted,
+  // permanently losing that update (the following unchanged-seed check would then treat it as
+  // already delivered, silently, since it looks identical to a genuinely static display). Shared by
+  // Start() (always called once, regardless of lastSeed_) and Tick() (only once a changed seed was
+  // already observed) so this ordering can't independently drift between the two again.
+  //
+  // Returns whether a frame was produced. Sets *error only for a genuine encode failure that
+  // should end the whole session; a false return with *error left nil means "transient, retry
+  // next tick" (mirrors VideoFrameEncoder::EncodeSurface's identical CVPixelBufferCreateWithIOSurface
+  // transient-failure contract in video_encoder.mm) — lastSeed_ is deliberately left stale then, so
+  // the next attempt retries this same content instead of silently skipping it forever.
+  bool EncodeCurrentSeedAndEmit(IOSurfaceRef surface, NSError** error) {
+    uint32_t seed = IOSurfaceGetSeed(surface);
+    NSData* data = nil;
+    bool encoded = EncodeSurface(surface, &data, error);
+    if (encoded) {
+      lastSeed_ = seed;
+      EmitFrame(data);
+    }
+    return encoded;
+  }
+
+  // Returns whether a frame was produced. Sets *error only for a genuine encode failure that
+  // should end the whole session; a false return with *error left nil means "transient, retry
+  // next tick" (mirrors VideoFrameEncoder::EncodeSurface's identical CVPixelBufferCreateWithIOSurface
+  // transient-failure contract in video_encoder.mm).
+  bool EncodeSurface(IOSurfaceRef surface, NSData** outData, NSError** error) {
+    CIImage* ciImage = [CIImage imageWithIOSurface:surface];
+    if (ciImage == nil) {
+      return false;
+    }
+    // Scaling the CIImage before rendering (rather than resizing an already-encoded JPEG
+    // afterward) means the CGImage/JPEG below is produced at the target resolution directly — no
+    // extra decode/resize/re-encode round trip.
+    if (std::fabs(options_.scale - 1.0) > kScaleEpsilon) {
+      ciImage = [ciImage imageByApplyingTransform:CGAffineTransformMakeScale(options_.scale, options_.scale)];
+    }
+    CGImageRef cgImage = [context_ createCGImage:ciImage fromRect:ciImage.extent];
+    if (cgImage == nil) {
+      return false;
+    }
+    // Same CGImageDestination-based encode CaptureScreenshot's kJPEG format uses (sim_screenshot.mm).
+    NSData* imageData = EncodeImage(cgImage, ScreenshotFormat::kJPEG, options_.jpegQualityPercent, error);
+    CGImageRelease(cgImage);
+    if (imageData == nil) {
+      return false;
+    }
+    *outData = imageData;
+    return true;
+  }
+
+  // Called either from Start() (on whichever thread calls it, before the timer/queue_ even starts
+  // running) or from Tick() (already serialized on queue_, once the timer is live) — never both at
+  // once, since Start() always finishes (and only then resumes the timer) before Tick() can fire.
+  // So sequence_ needs no synchronization, unlike VideoStreamSession's (whose encoder callback can
+  // run concurrently with the poll loop on a different thread).
+  void EmitFrame(NSData* data) {
+    JpegFrame frame;
+    frame.sequence = sequence_++;
+    frame.timestampMicros = static_cast<int64_t>((MonotonicSeconds() - startTime_) * 1000000);
+    const uint8_t* bytes = static_cast<const uint8_t*>(data.bytes);
+    frame.data.assign(bytes, bytes + data.length);
+    if (onFrame_) {
+      onFrame_(std::move(frame));
+    }
+  }
+
+  id device_;
+  JpegStreamOptions options_;
+  std::function<void(JpegFrame)> onFrame_;
+  std::function<void(NSError*)> onError_;
+  std::function<void()> onEnd_;
+  std::function<void()> onAbortDelivery_;
+
+  dispatch_queue_t queue_ = nullptr;
+  dispatch_source_t timer_ = nullptr;
+  CIContext* context_ = nil;
+  uint32_t lastSeed_ = 0;
+  double startTime_ = 0;
+  uint64_t sequence_ = 0;
+  // 0 means "no stall in progress" — set to MonotonicSeconds() by ReportIfStalledTooLong() on the
+  // first unproductive tick of a run, cleared back to 0 by any tick that makes real progress
+  // (a produced frame, or an unchanged-seed check confirming the surface itself is still fine).
+  double stalledSince_ = 0;
+  std::atomic<bool> running_{false};
+};
+
+JpegStreamSession::JpegStreamSession(id device, JpegStreamOptions options, std::function<void(JpegFrame)> onFrame,
+                                     std::function<void(NSError*)> onError, std::function<void()> onEnd,
+                                     std::function<void()> onAbortDelivery)
+    : impl_(std::make_unique<Impl>(device, options, std::move(onFrame), std::move(onError), std::move(onEnd),
+                                   std::move(onAbortDelivery))) {}
+
+JpegStreamSession::~JpegStreamSession() = default;
+
+void JpegStreamSession::Start() { impl_->Start(); }
+
+void JpegStreamSession::Stop() { impl_->Stop(); }
+
+void JpegStreamSession::AbortDelivery() { impl_->AbortDelivery(); }
+
+}  // namespace coresim

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_pasteboard.mm

@@ -69,7 +69,7 @@ namespace coresim {
 
 namespace {
 
-NSString* const kPasteboardErrorDomain = @"com.appium.coresim.Pasteboard";
+NSString* const kPasteboardErrorDomain = @"io.appium.coresim.Pasteboard";
 
 // The UTI both pasteboard mechanisms below exchange plain text under.
 NSString* const kPlainTextUTI = @"public.utf8-plain-text";
@@ -166,7 +166,7 @@ NSString* PullPasteboardStringModern(id device, NSError** error) {
     CoresimPasteboardDelegate* delegate = [CoresimPasteboardDelegate new];
     delegate.activeSema = dispatch_semaphore_create(0);
     delegate.appliedSema = dispatch_semaphore_create(0);
-    dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.pasteboard.pull", DISPATCH_QUEUE_SERIAL);
+    dispatch_queue_t queue = dispatch_queue_create("io.appium.coresim.pasteboard.pull", DISPATCH_QUEUE_SERIAL);
 
     id interface = ConnectPasteboardInterface(device, pasteboard, delegate, queue);
     SafeInvoke([&] {
@@ -200,7 +200,7 @@ BOOL PushPasteboardStringModern(id device, NSString* content, NSError** error) {
     CoresimPasteboardDelegate* delegate = [CoresimPasteboardDelegate new];
     delegate.activeSema = dispatch_semaphore_create(0);
     delegate.appliedSema = dispatch_semaphore_create(0);
-    dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.pasteboard.push", DISPATCH_QUEUE_SERIAL);
+    dispatch_queue_t queue = dispatch_queue_create("io.appium.coresim.pasteboard.push", DISPATCH_QUEUE_SERIAL);
 
     id interface = ConnectPasteboardInterface(device, pasteboard, delegate, queue);
     SafeInvoke([&] {

package/src/native/sim_process.mm

@@ -13,7 +13,7 @@ namespace coresim {
 
 namespace {
 
-NSString* const kProcessErrorDomain = @"com.appium.coresim.Process";
+NSString* const kProcessErrorDomain = @"io.appium.coresim.Process";
 NSString* const kWebInspectorSocketSuffix = @"com.apple.webinspectord_sim.socket";
 
 NSError* MakeError(NSInteger code, NSString* message) {

package/src/native/sim_screenshot.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#import <CoreGraphics/CoreGraphics.h>
 #import <Foundation/Foundation.h>
 
 namespace coresim {
@@ -17,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.
@@ -24,6 +30,13 @@ id CurrentDisplaySurface(id descriptor);
 
 enum class ScreenshotFormat { kPNG, kJPEG };
 
+// Encodes `cgImage` via ImageIO into `format` — the same CGImageDestination-based encode
+// CaptureScreenshot uses for its own final step, exposed for a caller that already has a
+// CGImageRef from its own CIContext (e.g. JpegStreamSession's persistent one — see
+// sim_jpeg_stream.mm). `jpegQualityPercent` semantics match CaptureScreenshot's own parameter of
+// the same name. Returns nil (and sets *error) on encode failure. Does not release `cgImage`.
+NSData* EncodeImage(CGImageRef cgImage, ScreenshotFormat format, NSNumber* jpegQualityPercent, NSError** error);
+
 // Captures a display as an image, reading the same in-process framebuffer surface `simctl io
 // <udid> screenshot` itself reads (see sim_screenshot.mm) — no temp file, no subprocess.
 // `displayId`, if non-nil, selects a specific port by its UUID (see ListDisplays); nil selects the