@appium/coresim 1.7.0 → 1.8.0

package/src/commands/jpeg-stream.ts

@@ -0,0 +1,233 @@
+import {EventEmitter} from 'node:events';
+
+import {logger} from '@appium/support';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import type {JpegFrame, JpegStreamOptions, NativeJpegStreamHandle} from '../types.js';
+import {runCatchingAsync, toTypedError} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    startJpegStream(udid: string, options?: JpegStreamOptions): Promise<JpegStream>;
+  }
+}
+
+const log = logger.getLogger('CoreSim');
+
+// Matches the native side's own ThreadSafeFunction queue bound (see coresim.mm's kFrameQueueSize).
+const MAX_BUFFERED_FRAMES = 60;
+
+const SINGLE_CONSUMER_ERROR =
+  'JpegStream.frames() supports only one active consumer at a time — a second concurrent call rejects.';
+
+/**
+ * Single-consumer FIFO between native's per-frame callback and `frames()`. Simpler than
+ * `AccessUnitQueue` (video-stream.ts): every JPEG frame is independently decodable, so there's no
+ * reference chain to protect — overflow just drops the oldest buffered frame(s), keeping delivery
+ * as close to real time as possible instead of falling further behind.
+ */
+class JpegFrameQueue {
+  private readonly buffer: JpegFrame[] = [];
+  private waiter: {resolve: (result: IteratorResult<JpegFrame>) => void; reject: (err: unknown) => void} | undefined;
+  private ended = false;
+  private error: unknown;
+
+  push(frame: JpegFrame): void {
+    if (this.ended) {
+      return;
+    }
+    if (this.waiter) {
+      const {resolve} = this.waiter;
+      this.waiter = undefined;
+      resolve({value: frame, done: false});
+      return;
+    }
+    this.buffer.push(frame);
+    if (this.buffer.length > MAX_BUFFERED_FRAMES) {
+      this.buffer.shift();
+    }
+  }
+
+  /** Ends the queue with an error — any pending or future `next()` rejects with it. */
+  fail(err: unknown): void {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.error = err;
+    this.buffer.length = 0;
+    if (this.waiter) {
+      const {reject} = this.waiter;
+      this.waiter = undefined;
+      reject(err);
+    }
+  }
+
+  /** Ends the queue cleanly — any pending or future `next()` resolves `done`. */
+  end(): void {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.buffer.length = 0;
+    if (this.waiter) {
+      const {resolve} = this.waiter;
+      this.waiter = undefined;
+      resolve({value: undefined, done: true});
+    }
+  }
+
+  /**
+   * Resolves `done` (not rejects) if `signal` aborts while waiting, mirroring `events.on()`.
+   * Checks cancellation/end *before* dequeuing, so an already-aborted signal or an already-ended
+   * queue never hands out a stale buffered frame.
+   */
+  next(signal: AbortSignal): Promise<IteratorResult<JpegFrame>> {
+    if (signal.aborted) {
+      return Promise.resolve({value: undefined, done: true});
+    }
+    if (this.ended) {
+      return this.error ? Promise.reject(this.error) : Promise.resolve({value: undefined, done: true});
+    }
+    const buffered = this.buffer.shift();
+    if (buffered !== undefined) {
+      return Promise.resolve({value: buffered, done: false});
+    }
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        this.waiter = undefined;
+        resolve({value: undefined, done: true});
+      };
+      signal.addEventListener('abort', onAbort, {once: true});
+      this.waiter = {
+        resolve: (result) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(result);
+        },
+        reject: (err) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(err);
+        },
+      };
+    });
+  }
+}
+
+/**
+ * A live JPEG frame stream from `NativeSimctl.startJpegStream` — polls the device's display and
+ * delivers each changed frame as a standalone JPEG image, at a configurable fps/quality. Unlike
+ * `startVideoStream`, this produces no video codec bitstream — it's meant for callers that want to
+ * build their own MJPEG (`multipart/x-mixed-replace`) HTTP stream, or otherwise just want a plain
+ * sequence of images, out of `frames()` themselves.
+ */
+export class JpegStream extends EventEmitter {
+  private handle: NativeJpegStreamHandle | undefined;
+  private readonly stopController = new AbortController();
+  private stopPromise: Promise<void> | undefined;
+  private readonly queue = new JpegFrameQueue();
+  private activeConsumers = 0;
+
+  /** @internal */
+  _handleFrame(frame: JpegFrame): void {
+    this.queue.push(frame);
+  }
+
+  /**
+   * @internal
+   * An active `frames()` consumer receives the error via the queue itself (thrown out of its
+   * `for await` loop, per that method's contract) rather than the `'error'` event, so `emit` is
+   * only used for an explicit external listener; with neither, it's logged instead of lost.
+   */
+  _handleError(err: unknown): void {
+    const error = toTypedError(err);
+    this.queue.fail(error);
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', error);
+    } else if (this.activeConsumers === 0) {
+      log.error(`Unhandled JpegStream error: ${error.stack ?? error}`);
+    }
+  }
+
+  /** @internal */
+  _attachHandle(handle: NativeJpegStreamHandle): void {
+    this.handle = handle;
+  }
+
+  /**
+   * Yields each JPEG frame as it's produced, until {@link stop} is called or the stream errors (in
+   * which case the error is thrown out of the loop). Pass `signal` to stop iterating without
+   * treating that as an error.
+   *
+   * Only one active consumer is supported at a time — a second concurrent call rejects rather than
+   * silently sharing (and corrupting) the first one's single internal waiter slot.
+   */
+  async *frames(signal?: AbortSignal): AsyncGenerator<JpegFrame> {
+    if (this.activeConsumers > 0) {
+      throw new Error(SINGLE_CONSUMER_ERROR);
+    }
+    const combined = signal ? AbortSignal.any([signal, this.stopController.signal]) : this.stopController.signal;
+    this.activeConsumers++;
+    try {
+      for (;;) {
+        const result = await this.queue.next(combined);
+        if (result.done) {
+          return;
+        }
+        yield result.value;
+      }
+    } finally {
+      this.activeConsumers--;
+    }
+  }
+
+  /** Stops the stream and releases the underlying encoder. Idempotent, including concurrently. */
+  async stop(): Promise<void> {
+    this.stopPromise ??= (async () => {
+      this.stopController.abort();
+      this.queue.end();
+      await this.handle?.stop();
+    })();
+    return this.stopPromise;
+  }
+}
+
+/**
+ * Starts polling the device's display and JPEG-encoding each changed frame in real time. Resolves
+ * once the encoder has actually started; the returned {@link JpegStream}'s `frames()` then yields
+ * each frame as it arrives. Independent of `startVideoStream`/`startVideoRecording` — any number of
+ * concurrent streams/recordings can run on the same device at once.
+ *
+ * @param udid — UDID of the device to stream; must be booted
+ * @param options — `displayId`, `fps`, `quality`, `scale` — see {@link JpegStreamOptions}
+ */
+export async function startJpegStream(
+  this: NativeSimctl,
+  udid: string,
+  options: JpegStreamOptions = {},
+): Promise<JpegStream> {
+  // The native poller clamps below 1 fps to 1 fps rather than actually polling that slowly, so a
+  // sub-1 value here would silently poll far more often than requested — rejected instead.
+  if (options.fps !== undefined && (!Number.isFinite(options.fps) || options.fps < 1)) {
+    throw new RangeError(`fps must be a finite number >= 1, got ${options.fps}`);
+  }
+  if (
+    options.quality !== undefined &&
+    (!Number.isFinite(options.quality) || options.quality < 0 || options.quality > 100)
+  ) {
+    throw new RangeError(`quality must be a number between 0 and 100, got ${options.quality}`);
+  }
+  if (options.scale !== undefined && (!Number.isFinite(options.scale) || options.scale <= 0 || options.scale > 100)) {
+    throw new RangeError(`scale must be a number greater than 0 and no greater than 100, got ${options.scale}`);
+  }
+  const device = await runCatchingAsync(() => this._findDevice(udid));
+  const stream = new JpegStream();
+  const handle = await runCatchingAsync(() =>
+    device.startJpegStream(
+      options,
+      (frame) => stream._handleFrame(frame),
+      (err) => stream._handleError(err),
+    ),
+  );
+  stream._attachHandle(handle);
+  return stream;
+}

package/src/coresim.mm

@@ -31,6 +31,7 @@
 #include "native/objc_runtime.h"
 #include "native/sim_device.h"
 #include "native/sim_device_set.h"
+#include "native/sim_jpeg_stream.h"
 #include "native/sim_pasteboard.h"
 #include "native/sim_process.h"
 #include "native/sim_screenshot.h"
@@ -99,7 +100,7 @@ NSError* MakeDescriptorError(NSString* which, int savedErrno) {
 }
 
 NSError* MakeSpawnPathError(NSString* message) {
-  return [NSError errorWithDomain:@"com.appium.coresim.spawn" code:1 userInfo:@{NSLocalizedDescriptionKey : message}];
+  return [NSError errorWithDomain:@"io.appium.coresim.spawn" code:1 userInfo:@{NSLocalizedDescriptionKey : message}];
 }
 
 // Standard bin dirs to search, in order, when `path` is a bare command name (no `/`) — mirrors
@@ -258,9 +259,11 @@ struct AddonInstanceData {
   Napi::FunctionReference avStreamConstructor;
   Napi::FunctionReference avRecordingConstructor;
   Napi::FunctionReference privateRecordingConstructor;
+  Napi::FunctionReference jpegStreamConstructor;
   ActiveSessionRegistry<coresim::VideoStreamSession> activeVideoStreams;
   ActiveSessionRegistry<coresim::AVStreamSession> activeAVStreams;
   ActiveSessionRegistry<coresim::AVRecordingSession> activeAVRecordings;
+  ActiveSessionRegistry<coresim::JpegStreamSession> activeJpegStreams;
 };
 
 }  // namespace
@@ -326,6 +329,58 @@ Napi::Object NativeVideoStream::NewInstance(Napi::Env env, std::shared_ptr<cores
       env, boxed, [](Napi::Env /*env*/, std::shared_ptr<coresim::VideoStreamSession>* data) { delete data; })});
 }
 
+// Wraps a live coresim::JpegStreamSession — same shape as NativeVideoStream minus
+// `requestKeyFrame()` (meaningless here: every JPEG frame is already independently decodable, see
+// sim_jpeg_stream.h). Frames/errors are delivered live via the callbacks passed directly to
+// startJpegStream, not through this object — it only exposes `stop()`.
+class NativeJpegStream : public Napi::ObjectWrap<NativeJpegStream> {
+ public:
+  static void Init(Napi::Env env);
+  static Napi::Object NewInstance(Napi::Env env, std::shared_ptr<coresim::JpegStreamSession> session);
+  explicit NativeJpegStream(const Napi::CallbackInfo& info);
+
+ private:
+  std::shared_ptr<coresim::JpegStreamSession> session_;
+
+  Napi::Value Stop(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    auto session = session_;
+    return RunAsyncVoid(env, [session]() { session->Stop(); });
+  }
+
+  // See NativeVideoStream::Finalize for why this hands off to a background queue.
+  void Finalize(Napi::Env env) override {
+    auto session = std::move(session_);
+    if (session) {
+      env.GetInstanceData<AddonInstanceData>()->activeJpegStreams.Deregister(session);
+      dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        session->Stop();
+      });
+    }
+  }
+};
+
+NativeJpegStream::NativeJpegStream(const Napi::CallbackInfo& info) : Napi::ObjectWrap<NativeJpegStream>(info) {
+  auto* boxed = info[0].As<Napi::External<std::shared_ptr<coresim::JpegStreamSession>>>().Data();
+  session_ = *boxed;
+  info.Env().GetInstanceData<AddonInstanceData>()->activeJpegStreams.Register(session_);
+}
+
+void NativeJpegStream::Init(Napi::Env env) {
+  Napi::Function ctor = DefineClass(env, "NativeJpegStream",
+                                    {
+                                        InstanceMethod<&NativeJpegStream::Stop>("stop"),
+                                    });
+  env.GetInstanceData<AddonInstanceData>()->jpegStreamConstructor = Napi::Persistent(ctor);
+}
+
+Napi::Object NativeJpegStream::NewInstance(Napi::Env env, std::shared_ptr<coresim::JpegStreamSession> session) {
+  auto* boxed = new std::shared_ptr<coresim::JpegStreamSession>(std::move(session));
+  Napi::Function ctor = env.GetInstanceData<AddonInstanceData>()->jpegStreamConstructor.Value();
+  return ctor.New({Napi::External<std::shared_ptr<coresim::JpegStreamSession>>::New(
+      env, boxed, [](Napi::Env /*env*/, std::shared_ptr<coresim::JpegStreamSession>* data) { delete data; })});
+}
+
 // Wraps a live coresim::AVStreamSession — the combined-AV counterpart to NativeVideoStream above,
 // same shape (only `stop()`/`requestKeyFrame()`; access units/errors are delivered live via the
 // callbacks passed directly to startAVStream).
@@ -473,7 +528,7 @@ class NativePrivateRecordingHandle : public Napi::ObjectWrap<NativePrivateRecord
     id device = device_;
     return RunAsyncVoid(env, [device]() {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
-      dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.stopRecordVideo", DISPATCH_QUEUE_SERIAL);
+      dispatch_queue_t queue = dispatch_queue_create("io.appium.coresim.stopRecordVideo", DISPATCH_QUEUE_SERIAL);
       __block NSError* capturedError = nil;
       NSError* resolveError = nil;
       BOOL ok = coresim::StopVideoRecording(
@@ -573,7 +628,7 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
     NSDictionary* options = OptionsArg(info, 0);
     return RunAsyncVoid(env, [device, options]() {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
-      dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.boot", DISPATCH_QUEUE_SERIAL);
+      dispatch_queue_t queue = dispatch_queue_create("io.appium.coresim.boot", DISPATCH_QUEUE_SERIAL);
       __block NSError* capturedError = nil;
       BootAsync(device, options, queue, ^(NSError* error) {
         capturedError = error;
@@ -1048,8 +1103,8 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
   static coresim::VideoEncoderOptions ParseVideoEncoderOptions(const Napi::CallbackInfo& info, size_t argIndex) {
     NSString* displayId = nil;
     coresim::VideoStreamCodec codec = coresim::VideoStreamCodec::kH264;
-    double fps = 15.0;
-    int bitrate = 2000000;
+    double fps = 60.0;
+    int bitrate = 4000000;
     if (info.Length() > argIndex && info[argIndex].IsObject()) {
       Napi::Object options = info[argIndex].As<Napi::Object>();
       if (options.Has("displayId") && options.Get("displayId").IsString()) {
@@ -1069,6 +1124,37 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
     return coresim::VideoEncoderOptions{codec, displayId, fps, bitrate};
   }
 
+  // `quality`/`displayId`/`fps` are this addon's own options, not a CoreSimulator options
+  // dictionary — the TS layer (commands/jpeg-stream.ts) already constrains them, so anything else
+  // (including absent) is just defaulted here rather than validated again (mirrors Screenshot's
+  // identical comment above).
+  static coresim::JpegStreamOptions ParseJpegStreamOptions(const Napi::CallbackInfo& info, size_t argIndex) {
+    NSString* displayId = nil;
+    double fps = 60.0;
+    // Defaults to 80, not ImageIO's own (near-lossless, much larger) default — see
+    // JpegStreamOptions's own comment (sim_jpeg_stream.h) for why.
+    NSNumber* jpegQualityPercent = @80;
+    double scale = 1.0;
+    if (info.Length() > argIndex && info[argIndex].IsObject()) {
+      Napi::Object options = info[argIndex].As<Napi::Object>();
+      if (options.Has("displayId") && options.Get("displayId").IsString()) {
+        displayId = @(options.Get("displayId").As<Napi::String>().Utf8Value().c_str());
+      }
+      if (options.Has("fps") && options.Get("fps").IsNumber()) {
+        fps = options.Get("fps").As<Napi::Number>().DoubleValue();
+      }
+      if (options.Has("quality") && options.Get("quality").IsNumber()) {
+        jpegQualityPercent = @(options.Get("quality").As<Napi::Number>().DoubleValue());
+      }
+      // JS-facing `scale` is a 1-100 percent (commands/jpeg-stream.ts already validates the
+      // range), converted here to the 0.0-1.0 fraction JpegStreamSession actually applies.
+      if (options.Has("scale") && options.Get("scale").IsNumber()) {
+        scale = options.Get("scale").As<Napi::Number>().DoubleValue() / 100.0;
+      }
+    }
+    return coresim::JpegStreamOptions{displayId, fps, jpegQualityPercent, scale};
+  }
+
   static bool OptionsWantAudio(const Napi::CallbackInfo& info, size_t argIndex) {
     return info.Length() > argIndex && info[argIndex].IsObject() && info[argIndex].As<Napi::Object>().Has("audio") &&
            info[argIndex].As<Napi::Object>().Get("audio").IsBoolean() &&
@@ -1132,7 +1218,7 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
         env,
         [device, displayId, mask, assetWriterOutputSettings, outputFile]() -> id {
           dispatch_semaphore_t sema = dispatch_semaphore_create(0);
-          dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.recordVideo", DISPATCH_QUEUE_SERIAL);
+          dispatch_queue_t queue = dispatch_queue_create("io.appium.coresim.recordVideo", DISPATCH_QUEUE_SERIAL);
           __block NSError* capturedError = nil;
           NSError* resolveError = nil;
           BOOL ok = coresim::StartVideoRecording(
@@ -1380,6 +1466,81 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
         });
   }
 
+  // Real-time JPEG frame stream via ImageIO (see sim_jpeg_stream.mm) — a client-side MJPEG stream
+  // is just this frame sequence multipart-boundary-framed over HTTP, which coresim itself has no
+  // opinion about. Same TSFN/registry/teardown shape as StartVideoStream's audio-less branch,
+  // minus keyframes/resync (every JPEG frame is independently decodable).
+  Napi::Value StartJpegStream(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    id device = device_;
+    coresim::JpegStreamOptions options = ParseJpegStreamOptions(info, 0);
+    Napi::Function onFrame = info[1].As<Napi::Function>();
+    Napi::Function onError = info[2].As<Napi::Function>();
+
+    // See StartVideoStream's identical comment on accessUnitTsfn — bounded so a slow-draining
+    // consumer throttles the encoder via BlockingCall instead of letting queued frames grow
+    // unbounded.
+    static constexpr size_t kFrameQueueSize = 60;
+    Napi::ThreadSafeFunction frameTsfn =
+        Napi::ThreadSafeFunction::New(env, onFrame, "coresim jpeg stream frame", kFrameQueueSize, 1);
+    Napi::ThreadSafeFunction errorTsfn = Napi::ThreadSafeFunction::New(env, onError, "coresim jpeg stream error", 0, 1);
+    auto tsfnGuard = std::make_shared<TsfnReleaseGuard>();
+
+    return RunAsync<std::shared_ptr<coresim::JpegStreamSession>>(
+        env,
+        [device, options, frameTsfn, errorTsfn, tsfnGuard]() mutable -> std::shared_ptr<coresim::JpegStreamSession> {
+          auto session = std::make_shared<coresim::JpegStreamSession>(
+              device, options,
+              [frameTsfn](coresim::JpegFrame frame) mutable {
+                frameTsfn.BlockingCall([frame = std::move(frame)](Napi::Env env, Napi::Function jsCallback) mutable {
+                  // See StartVideoStream's identical comment on why this is wrapped in try/catch.
+                  try {
+                    Napi::Object obj = Napi::Object::New(env);
+                    obj.Set("data", Napi::Buffer<uint8_t>::Copy(env, frame.data.data(), frame.data.size()));
+                    obj.Set("sequence", Napi::Number::New(env, static_cast<double>(frame.sequence)));
+                    obj.Set("timestampMicros", Napi::Number::New(env, static_cast<double>(frame.timestampMicros)));
+                    jsCallback.Call({obj});
+                  } catch (...) {
+                  }
+                });
+              },
+              [errorTsfn](NSError* error) mutable {
+                NSErrorException exception(error);
+                errorTsfn.BlockingCall([exception](Napi::Env env, Napi::Function jsCallback) {
+                  try {
+                    jsCallback.Call({NSErrorExceptionToJsError(env, exception).Value()});
+                  } catch (...) {
+                  }
+                });
+              },
+              [frameTsfn, errorTsfn, tsfnGuard]() mutable {
+                ReleaseTsfnOnce(tsfnGuard, [&]() mutable {
+                  frameTsfn.Release();
+                  errorTsfn.Release();
+                });
+              },
+              [frameTsfn, errorTsfn, tsfnGuard]() mutable {
+                ReleaseTsfnOnce(tsfnGuard, [&]() mutable {
+                  frameTsfn.Abort();
+                  errorTsfn.Abort();
+                });
+              });
+          try {
+            session->Start();
+          } catch (...) {
+            ReleaseTsfnOnce(tsfnGuard, [&]() mutable {
+              frameTsfn.Release();
+              errorTsfn.Release();
+            });
+            throw;
+          }
+          return session;
+        },
+        [](Napi::Env env, std::shared_ptr<coresim::JpegStreamSession> session) -> Napi::Value {
+          return NativeJpegStream::NewInstance(env, session);
+        });
+  }
+
   // Option dictionary keys for `spawnWithPath:options:...` aren't part of the ObjC runtime
   // metadata this addon resolves selectors from (they're string literals inside CoreSimulator's
   // own implementation) — confirmed by resolving each `SimDeviceSpawnKey*` symbol at runtime via
@@ -1567,6 +1728,7 @@ void NativeDevice::Init(Napi::Env env) {
                       InstanceMethod<&NativeDevice::GetDisplays>("getDisplays"),
                       InstanceMethod<&NativeDevice::StartVideoRecording>("startVideoRecording"),
                       InstanceMethod<&NativeDevice::StartVideoStream>("startVideoStream"),
+                      InstanceMethod<&NativeDevice::StartJpegStream>("startJpegStream"),
                       InstanceMethod<&NativeDevice::Spawn>("spawn"),
                   });
   env.GetInstanceData<AddonInstanceData>()->deviceConstructor = Napi::Persistent(ctor);
@@ -1818,6 +1980,7 @@ void CleanupActiveSessions(AddonInstanceData* instanceData) {
   };
   instanceData->activeVideoStreams.StopAll(stopStream);
   instanceData->activeAVStreams.StopAll(stopStream);
+  instanceData->activeJpegStreams.StopAll(stopStream);
   instanceData->activeAVRecordings.StopAll([](auto& session) {
     dispatch_semaphore_t sema = dispatch_semaphore_create(0);
     session->Stop([sema](NSError*) { dispatch_semaphore_signal(sema); });
@@ -1850,6 +2013,7 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
   NativeAVStream::Init(env);
   NativeAVRecording::Init(env);
   NativePrivateRecordingHandle::Init(env);
+  NativeJpegStream::Init(env);
   exports.Set("sharedServiceContext", Napi::Function::New(env, SharedServiceContextBinding));
   exports.Set("frameworkVersion", Napi::Function::New(env, FrameworkVersionBinding));
   exports.Set("flushActiveSessions", Napi::Function::New(env, FlushActiveSessionsBinding));

package/src/index.ts

@@ -2,6 +2,7 @@ export {NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, Nativ
 export {NativeSimctl} from './native-simctl.js';
 export {SpawnedProcess} from './commands/spawn.js';
 export {VideoStream} from './commands/video-stream.js';
+export {JpegStream} from './commands/jpeg-stream.js';
 export type {AppContainerType} from './commands/app.js';
 export type {BiometricName} from './commands/biometric.js';
 export {
@@ -10,6 +11,8 @@ export {
   type ApnsAlert,
   type ApnsPayload,
   type ApnsSound,
+  type JpegFrame,
+  type JpegStreamOptions,
   type PushNotificationPayload,
   type ScreenshotOptions,
   type SimBootInfo,

package/src/native/audio_encoder.mm

@@ -12,7 +12,7 @@ namespace coresim {
 
 namespace {
 
-NSString* const kAudioEncoderErrorDomain = @"com.appium.coresim.AudioEncoder";
+NSString* const kAudioEncoderErrorDomain = @"io.appium.coresim.AudioEncoder";
 
 NSError* MakeError(NSInteger code, NSString* message) {
   return [NSError errorWithDomain:kAudioEncoderErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];

package/src/native/av_recording.mm

@@ -13,7 +13,7 @@ namespace coresim {
 
 namespace {
 
-NSString* const kAVRecordingErrorDomain = @"com.appium.coresim.AVRecording";
+NSString* const kAVRecordingErrorDomain = @"io.appium.coresim.AVRecording";
 
 NSError* MakeError(NSInteger code, NSString* message) {
   return [NSError errorWithDomain:kAVRecordingErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];

package/src/native/sim_audio_tap.mm

@@ -11,7 +11,7 @@
 
 namespace coresim {
 
-NSString* const kAudioTapErrorDomain = @"com.appium.coresim.AudioTap";
+NSString* const kAudioTapErrorDomain = @"io.appium.coresim.AudioTap";
 
 namespace {
 
@@ -66,7 +66,7 @@ class AudioTapSession::Impl {
   Impl(NSString* udid, std::function<void(const AudioBufferList*, const AudioTimeStamp*)> onBuffer,
        std::function<void(NSError*)> onError, std::function<void()> onEnd)
       : udid_(udid), onBuffer_(std::move(onBuffer)), onError_(std::move(onError)), onEnd_(std::move(onEnd)) {
-    queue_ = dispatch_queue_create("com.appium.coresim.audioTap", DISPATCH_QUEUE_SERIAL);
+    queue_ = dispatch_queue_create("io.appium.coresim.audioTap", DISPATCH_QUEUE_SERIAL);
   }
 
   ~Impl() { Stop(); }
@@ -154,7 +154,7 @@ class AudioTapSession::Impl {
     NSDictionary* aggregateDescription = @{
       @(kAudioAggregateDeviceNameKey) : [NSString stringWithFormat:@"coresim-audio-%@", udid_],
       @(kAudioAggregateDeviceUIDKey) :
-          [NSString stringWithFormat:@"com.appium.coresim.audio.%@.%@", udid_, uuid.UUIDString],
+          [NSString stringWithFormat:@"io.appium.coresim.audio.%@.%@", udid_, uuid.UUIDString],
       @(kAudioAggregateDeviceIsPrivateKey) : @YES,
       @(kAudioAggregateDeviceTapAutoStartKey) : @NO,
       @(kAudioAggregateDeviceTapListKey) : @[ @{

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