serve-sim 0.1.49-beta.134.1 → 0.1.49-beta.136.1

package/README.md

@@ -40,8 +40,8 @@ Requires macOS with Xcode command line tools (`xcrun simctl`) and a [maintained
 
 ## iPhone Duo
 
-With Xcode 27.1 and the iOS 27.1 runtime, the preview exposes **Folded**,
-**Semi-folded**, and **Fully open** controls for iPhone Duo. Selecting one drives
+With Xcode 27.1 and the iOS 27.1 runtime, the preview exposes **Closed**,
+**Book**, and **Open** controls for iPhone Duo. Selecting one drives
 the simulator's hinge and follows the active panel's framebuffer. Touches use the panel's own
 integrated digitizer; volume and power controls use a guest HID service.
 
@@ -71,9 +71,9 @@ press-and-hold. The main control bar has no volume menu or 2D/3D mode toggle.
 See the [feature contract and regression checklist](../../.agents/skills/serve-sim-duo-verification/references/expected-behavior.md)
 for appearance, folding, rotation, controls, screenshot, and performance checks.
 
-The preview follows hinge changes made in Device Hub. Closed (0°), Tent (80°),
-Table (100°), Book (130°), and Open (180°) are angle presets; use Rotate for
-orientation. SpringBoard primary-display events choose the captured panel,
+The preview follows hinge changes made in Device Hub. The pose toolbar offers
+exactly three presets: Closed (0°), Book (130°), and Open (180°). Set any other
+angle with `serve-sim fold <deg>`; use Rotate for orientation. SpringBoard primary-display events choose the captured panel,
 including intermediate poses that depend on whether you were opening or closing.
 Until guest readback arrives, a 90° threshold provides the initial fallback.
 The runtime decides which intermediate poses apps adopt.
@@ -141,6 +141,10 @@ Options:
       --codec <codec> Stream codec for the preview UI: 'auto' (H.264 when the
                       browser can decode it) or 'mjpeg' (force software JPEG —
                       e.g. on VMs without H.264 encode)
+      --max-bitrate <Mbps>
+                      Cap the H.264 stream bitrate (default scales with
+                      screen size, 6-30 Mbps). Also read from
+                      SERVE_SIM_MAX_BITRATE
       --list [device] List running streams
       --kill [device] Kill running stream(s)
 
@@ -167,6 +171,7 @@ serve-sim --kill                       # stop all helpers
 serve-sim --panes devices,tools --fit  # start with selected panes open and fit the simulator
 serve-sim --theme dark                 # start the simulator in Dark Mode
 serve-sim --allow-exec                 # enable `serve-sim exec` and .ipa drag-to-install
+serve-sim --max-bitrate 8              # cap H.264 at 8 Mbps (slow links / shared hosts)
 
 # Type text into the focused field
 serve-sim type "Hello, world!"

package/Sources/SimNative/CaptureEngine.swift

@@ -13,13 +13,23 @@ import os
 struct Frame: Identifiable {
     let id = UUID()
     let pixelBuffer: CVPixelBuffer
+    /// False when `pixelBuffer` wraps SimulatorKit's live framebuffer surface
+    /// (no pixel consumer was attached, so the private copy was skipped). Such
+    /// frames are only good for their dimensions.
+    var isPrivateCopy = true
 }
 
 protocol FrameEncoder {
     associatedtype Encoded
+    /// Whether this encoder reads pixels (and so needs a private frame copy).
+    static var readsPixels: Bool { get }
     func encode(_ frame: Frame) async throws -> Encoded
 }
 
+extension FrameEncoder {
+    static var readsPixels: Bool { true }
+}
+
 protocol CaptureConsuming: Sendable {
     // this is intentionally synchronous. CaptureEngine sends all frames to all consumers,
     // and lets them handle internal backpressure as they see fit. if instead this were async
@@ -66,6 +76,7 @@ actor CaptureConsumer<E: FrameEncoder>: CaptureConsuming {
     }
 
     nonisolated func handleFrame(_ frame: Frame) {
+        if E.readsPixels, !frame.isPrivateCopy { return }
         continuation.yield(frame)
     }
 
@@ -81,18 +92,27 @@ actor CaptureEngine {
     }
 
     private let deviceUDID: String
+    /// Optional cap (bits/s) on the resolution-scaled H.264 bitrate.
+    private let maxBitrate: Int?
     private let frameCapture = FrameCapture()
     private var phase = Phase.unstarted
 
     // mjpeg is stateless so we can share a single encoder instance
     private let mjpegEncoder = MJPEGEncoder()
     private let encoderDiagnostics = EncoderDiagnostics()
+    // Separate so viewer seeds don't queue behind (or evict the cache of)
+    // per-frame MJPEG viewer encodes.
+    private let snapshotEncoder = MJPEGEncoder()
 
     private(set) var screenSize = Dimensions(width: 0, height: 0)
     private var consumers = [UUID: CaptureConsuming]()
+    /// Number of attached consumers that read pixels. FrameCapture only pays
+    /// for the private per-frame copy while this is non-zero.
+    private let pixelConsumers = PixelConsumerCount()
 
-    init(deviceUDID: String) {
+    init(deviceUDID: String, maxBitrate: Int? = nil) {
         self.deviceUDID = deviceUDID
+        self.maxBitrate = maxBitrate
     }
 
     func setPreferredScreenSize(width: Int, height: Int) async {
@@ -124,8 +144,8 @@ actor CaptureEngine {
             bufferingPolicy: .bufferingNewest(1)
         )
         do {
-            try await frameCapture.start(deviceUDID: deviceUDID) { pixelBuffer, _ in
-                frameContinuation.yield(Frame(pixelBuffer: pixelBuffer))
+            try await frameCapture.start(deviceUDID: deviceUDID, pixelConsumers: pixelConsumers) { pixelBuffer, _, isCopy in
+                frameContinuation.yield(Frame(pixelBuffer: pixelBuffer, isPrivateCopy: isCopy))
             }
         } catch {
             // Preserve retryability after an ordinary start failure, but never
@@ -161,13 +181,21 @@ actor CaptureEngine {
         }
         let id = UUID()
         consumers[id] = consumer
-        return { await self.removeConsumer(id) }
+        if E.readsPixels {
+            pixelConsumers.increment()
+            // Emit a copied frame now rather than waiting for the next screen
+            // change or idle tick, so a new viewer's first IDR is immediate.
+            Task { [frameCapture] in await frameCapture.requestFrame() }
+        }
+        return { await self.removeConsumer(id, readsPixels: E.readsPixels) }
     }
 
     private func removeConsumer(
-        _ id: UUID
+        _ id: UUID,
+        readsPixels: Bool
     ) {
-        consumers.removeValue(forKey: id)
+        guard consumers.removeValue(forKey: id) != nil else { return }
+        if readsPixels { pixelConsumers.decrement() }
     }
 
     private func handleFrame(_ frame: Frame) {
@@ -178,6 +206,27 @@ actor CaptureEngine {
         }
     }
 
+    /// Reports the screen size with the first frame after subscribing (at most
+    /// one idle tick away) and whenever it changes, without encoding anything.
+    func addSizeConsumer(
+        onSize: sending @escaping (Dimensions) async -> Void
+    ) -> (@Sendable () async -> Void) {
+        var last: Dimensions?
+        return addConsumer(encoder: SizeEncoder()) { size in
+            guard size != last else { return }
+            last = size
+            await onSize(size)
+        }
+    }
+
+    /// JPEG of the current screen, encoded on demand. Used to seed new viewers
+    /// so the session doesn't JPEG-encode every frame just in case.
+    func snapshotJPEG() async throws -> (Dimensions, Data)? {
+        guard phase == .running, let pixelBuffer = await frameCapture.copyCurrentFrame() else { return nil }
+        let frame = Frame(pixelBuffer: pixelBuffer)
+        return (frame.pixelBuffer.dimensions, try await snapshotEncoder.encode(frame))
+    }
+
     func addMJPEGConsumer(
         onFrame: sending @escaping (Dimensions, Data) async -> Void
     ) -> (@Sendable () async -> Void) {
@@ -190,7 +239,7 @@ actor CaptureEngine {
     func addAVCCConsumer(
         onFrame: sending @escaping (Dimensions, Data, Int32) async -> Void
     ) -> (@Sendable () async -> Void) {
-        addConsumer(encoder: AVCCEncoder(diagnostics: encoderDiagnostics)) { [weak self] encoded in
+        addConsumer(encoder: AVCCEncoder(diagnostics: encoderDiagnostics, maxBitrate: maxBitrate)) { [weak self] encoded in
             let flagDescription: Int32 = 1 << 0
             let flagKeyframe: Int32 = 1 << 1
 
@@ -224,9 +273,26 @@ actor CaptureEngine {
         phase = .stopped
         Task { [frameCapture] in await frameCapture.stop() }
         consumers.removeAll()
+        pixelConsumers.reset()
     }
 }
 
+struct SizeEncoder: FrameEncoder {
+    static var readsPixels: Bool { false }
+    func encode(_ frame: Frame) async throws -> Dimensions { frame.pixelBuffer.dimensions }
+}
+
+/// Lock-protected count shared by CaptureEngine (writer) and FrameCapture
+/// (reader on its capture queue).
+final class PixelConsumerCount: @unchecked Sendable {
+    private let lock = NSLock()
+    private var count = 0
+    func increment() { lock.lock(); count += 1; lock.unlock() }
+    func decrement() { lock.lock(); count = max(0, count - 1); lock.unlock() }
+    func reset() { lock.lock(); count = 0; lock.unlock() }
+    var isEmpty: Bool { lock.lock(); defer { lock.unlock() }; return count == 0 }
+}
+
 actor MJPEGEncoder: FrameEncoder {
     private let videoEncoder = VideoEncoder(quality: 0.7)
     private var lastImage: (UUID, Data)?
@@ -247,8 +313,8 @@ actor AVCCEncoder: FrameEncoder {
     let h264Encoder: H264Encoder
     var forceKeyframe = true
 
-    init(diagnostics: EncoderDiagnostics? = nil) {
-        h264Encoder = H264Encoder(fps: 60, diagnostics: diagnostics)
+    init(diagnostics: EncoderDiagnostics? = nil, maxBitrate: Int? = nil) {
+        h264Encoder = H264Encoder(fps: 60, maxBitrate: maxBitrate, diagnostics: diagnostics)
     }
 
     func encode(_ frame: Frame) async throws -> H264Encoder.Encoded? {

package/Sources/SimNative/FrameCapture.swift

@@ -18,13 +18,14 @@ actor FrameCapture {
     nonisolated var unownedExecutor: UnownedSerialExecutor { queue.asUnownedSerialExecutor() }
 
     private var photocopier = Photocopier()
-    private var onFrame: ((CVPixelBuffer, CMTime) -> Void)?
+    private var onFrame: ((CVPixelBuffer, CMTime, Bool) -> Void)?
+    private var pixelConsumers: PixelConsumerCount?
     private var frameCount: UInt64 = 0
     private(set) var capturedWidth: Int = 0
     private(set) var capturedHeight: Int = 0
     private var idleTimer: Task<Void, Never>?
     private var lastCaptureTime: ContinuousClock.Instant = .now
-    private var lastSeeds: [ObjectIdentifier: UInt32] = [:]
+    private var lastStamps: [ObjectIdentifier: SurfaceFrameStamp] = [:]
     private var rewireTickCount: Int = 0
     /// Interval at which the idle timer re-emits the current frame even when
     /// the simulator isn't rendering anything new. This is load-bearing for two
@@ -50,9 +51,19 @@ actor FrameCapture {
     private var lastSelectedIndex: Int?
     private var lastSelectionReason = "none"
     private var sizeChanges: [[String: Any]] = []
-
-    func start(deviceUDID: String, onFrame: @escaping @Sendable (CVPixelBuffer, CMTime) -> Void) throws {
+    private var sourceCache = FramebufferSourceCache<FramebufferSource>(maxAge: 1.0)
+    private var recheckGeneration: UInt64 = 0
+
+    /// `onFrame(buffer, timestamp, isPrivateCopy)`: frames are deep-copied only
+    /// while `pixelConsumers` is non-empty; otherwise the buffer wraps the live
+    /// framebuffer surface and is only good for its dimensions.
+    func start(
+        deviceUDID: String,
+        pixelConsumers: PixelConsumerCount,
+        onFrame: @escaping @Sendable (CVPixelBuffer, CMTime, Bool) -> Void
+    ) throws {
         self.onFrame = onFrame
+        self.pixelConsumers = pixelConsumers
 
         SimFrameworks.load()
         guard let device = Self.findSimDevice(udid: deviceUDID) else {
@@ -105,7 +116,8 @@ actor FrameCapture {
             }
         }
         callbackUUIDs.removeAll()
-        lastSeeds.removeAll()
+        lastStamps.removeAll()
+        sourceCache.invalidate()
         descriptors = candidates
 
         // Registering screen callbacks is what causes SimulatorKit to wire the
@@ -234,15 +246,38 @@ actor FrameCapture {
         let uuid = UUID()
         callbackUUIDs[ObjectIdentifier(desc)] = uuid
 
+        // Explicitly typed locals keep the type checker from choking on the
+        // dynamic AnyObject call (some Xcode swiftc builds crash otherwise).
+        let frameCallback: @convention(block) () -> Void = { [self, weak desc] in
+            assumeIsolated { capture in
+                capture.onFrameCallback(from: desc)
+            }
+        }
+        let surfacesChangedCallback: @convention(block) () -> Void = { [self] in
+            assumeIsolated { capture in
+                _ = capture.captureFrame(trigger: .surfacesChanged)
+            }
+        }
+        let propertiesChangedCallback: @convention(block) () -> Void = {}
+
         desc.registerScreenCallbacks(
             uuid: uuid,
             callbackQueue: queue,
-            frameCallback: { [self] in assumeIsolated { $0.captureFrame() } },
-            surfacesChangedCallback: { [self] in assumeIsolated { $0.captureFrame() } },
-            propertiesChangedCallback: {}
+            frameCallback: frameCallback,
+            surfacesChangedCallback: surfacesChangedCallback,
+            propertiesChangedCallback: propertiesChangedCallback
         )
     }
 
+    /// `desc` is nil once the registering descriptor has been released.
+    private func onFrameCallback(from desc: AnyObject?) {
+        var fromCached = false
+        if let desc, let current = sourceCache.current?.descriptor {
+            fromCached = current === desc
+        }
+        onFrameCallback(trigger: fromCached ? .frame : .otherDescriptorFrame)
+    }
+
     private func startIdleTimer() {
         self.idleTimer = Task { [weak self] in
             while !Task.isCancelled {
@@ -256,7 +291,7 @@ actor FrameCapture {
     private func onIdleTimerTick() {
         let now = ContinuousClock.now
         guard (now - self.lastCaptureTime) >= Self.idleInterval else { return }
-        self.captureFrame(force: true)
+        self.captureFrame(force: true, trigger: .idleTick)
         // Self-heal: if we've never captured a frame, the cached descriptor
         // is likely stale. Re-wire the pipeline periodically (every ~1s)
         // until frames start flowing.
@@ -274,27 +309,41 @@ actor FrameCapture {
 
     // MARK: - Frame capture
 
-    private func captureFrame(force: Bool = false) {
-        guard let desc = pickBestDescriptor() else { return }
-
+    /// Resolve the selected descriptor and its current IOSurface. Every
+    /// `framebufferSurface` read is an XPC round-trip, so frame callbacks go
+    /// through `sourceCache` instead of calling this directly.
+    private func resolveSource() -> FramebufferSource? {
+        guard let desc = pickBestDescriptor() else { return nil }
         let surfSel = NSSelectorFromString("framebufferSurface")
-        guard let surfObj = desc.perform(surfSel)?.takeUnretainedValue() else { return }
-        let surface = unsafeBitCast(surfObj, to: IOSurface.self)
+        guard let surfObj = desc.perform(surfSel)?.takeUnretainedValue() else { return nil }
+        return FramebufferSource(descriptor: desc, surface: unsafeBitCast(surfObj, to: IOSurface.self))
+    }
+
+    /// Returns false only when the frame was skipped because the surface and
+    /// its seed hadn't changed (see `onFrameCallback`).
+    @discardableResult
+    private func captureFrame(force: Bool = false, trigger: FramebufferSourceCache<FramebufferSource>.Trigger = .frame) -> Bool {
+        let now = Double(DispatchTime.now().uptimeNanoseconds) / 1e9
+        guard let source = sourceCache.source(for: trigger, now: now, resolve: resolveSource) else { return true }
+        let desc = source.descriptor
+        let surface = source.surface
 
         // Seed-skip: when the simulator's framebuffer content hasn't changed,
         // don't spend cycles re-encoding the same pixels back-to-back from the
         // frame-callback path. BUT: we must still re-emit at the idle floor
         // (~5 fps) so that downstream consumers keep seeing a live stream —
-        // see the `idleInterval` doc-comment for why that matters.
+        // see the `idleInterval` doc-comment for why that matters. The surface
+        // ID is part of the stamp so a swapped-in surface whose seed happens to
+        // match the old one's still counts as new content.
         let key = ObjectIdentifier(desc)
-        let seed = IOSurfaceGetSeed(surface)
-        let seedChanged = lastSeeds[key] != seed
-        if frameCount > 0, !seedChanged, !force { return }
-        lastSeeds[key] = seed
+        let stamp = SurfaceFrameStamp(surfaceID: IOSurfaceGetID(surface), seed: IOSurfaceGetSeed(surface))
+        let contentChanged = lastStamps[key] != stamp
+        if frameCount > 0, !contentChanged, !force { return false }
+        lastStamps[key] = stamp
 
         let w = IOSurfaceGetWidth(surface)
         let h = IOSurfaceGetHeight(surface)
-        guard w > 0, h > 0 else { return }
+        guard w > 0, h > 0 else { return true }
 
         if capturedWidth != w || capturedHeight != h {
             let from = "\(capturedWidth)x\(capturedHeight)"
@@ -317,13 +366,39 @@ actor FrameCapture {
             [kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_32BGRA] as CFDictionary,
             &pixelBuffer
         )
-        guard status == kCVReturnSuccess, let pb = pixelBuffer?.takeRetainedValue() else { return }
+        guard status == kCVReturnSuccess, let pb = pixelBuffer?.takeRetainedValue() else { return true }
 
         lastCaptureTime = .now
         frameCount += 1
         let timestamp = CMTime(value: CMTimeValue(frameCount), timescale: 60)
-        guard let copy = photocopier.copy(pb) else { return }
-        onFrame?(copy, timestamp)
+        if pixelConsumers?.isEmpty ?? false {
+            onFrame?(pb, timestamp, false)
+            return true
+        }
+        guard let copy = photocopier.copy(pb) else { return true }
+        onFrame?(copy, timestamp, true)
+        return true
+    }
+
+    /// Frame callbacks can arrive before the surface seed reflects the new
+    /// frame. If this one finds the seed unchanged, re-check briefly instead of
+    /// leaving the frame for the idle tick. A newer callback supersedes it.
+    private func onFrameCallback(trigger: FramebufferSourceCache<FramebufferSource>.Trigger) {
+        recheckGeneration &+= 1
+        if captureFrame(trigger: trigger) { return }
+        scheduleSeedRecheck(generation: recheckGeneration, attempt: 0)
+    }
+
+    private func scheduleSeedRecheck(generation: UInt64, attempt: Int) {
+        guard let delay = SeedRecheckSchedule.delayMs(afterAttempt: attempt) else { return }
+        queue.asyncAfter(deadline: .now() + .milliseconds(delay)) { [weak self] in
+            self?.assumeIsolated { capture in
+                guard capture.recheckGeneration == generation, capture.onFrame != nil else { return }
+                if !capture.captureFrame() {
+                    capture.scheduleSeedRecheck(generation: generation, attempt: attempt + 1)
+                }
+            }
+        }
     }
 
     func getScreenSize() -> (width: Int, height: Int)? {
@@ -344,8 +419,10 @@ actor FrameCapture {
         }
         callbackUUIDs.removeAll()
         descriptors.removeAll()
-        lastSeeds.removeAll()
+        lastStamps.removeAll()
+        sourceCache.invalidate()
         onFrame = nil
+        pixelConsumers = nil
         frameCount = 0
         capturedWidth = 0
         capturedHeight = 0
@@ -362,6 +439,28 @@ actor FrameCapture {
         sizeChanges = []
     }
 
+    /// Emit the current screen now (e.g. a viewer just subscribed).
+    func requestFrame() {
+        captureFrame(force: true)
+    }
+
+    /// A private copy of the current screen, for one-off snapshots. Taken at
+    /// call time from the cached surface rather than retaining a wrapper of
+    /// SimulatorKit's live (recycled) framebuffer between frames.
+    func copyCurrentFrame() -> CVPixelBuffer? {
+        let now = Double(DispatchTime.now().uptimeNanoseconds) / 1e9
+        guard frameCount > 0,
+              let source = sourceCache.source(for: .frame, now: now, resolve: resolveSource) else { return nil }
+        var pixelBuffer: Unmanaged<CVPixelBuffer>?
+        let status = CVPixelBufferCreateWithIOSurface(
+            kCFAllocatorDefault, source.surface,
+            [kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_32BGRA] as CFDictionary,
+            &pixelBuffer
+        )
+        guard status == kCVReturnSuccess, let pb = pixelBuffer?.takeRetainedValue() else { return nil }
+        return photocopier.copy(pb)
+    }
+
     func setPreferredScreenSize(width: Int, height: Int) {
         if width > 0, height > 0 {
             preferredScreenSize = FramebufferSurfaceSize(width: width, height: height)
@@ -370,7 +469,7 @@ actor FrameCapture {
         }
         didLogRejectedPresentationSurface = false
         didLogMissingExpectedSurface = false
-        captureFrame(force: true)
+        captureFrame(force: true, trigger: .preferredSizeChanged)
     }
 
     /// JSON snapshot of display selection for `serve-sim doctor`.
@@ -502,6 +601,11 @@ actor FrameCapture {
     }
 }
 
+struct FramebufferSource {
+    let descriptor: NSObject
+    let surface: IOSurface
+}
+
 @objc protocol FramebufferDescriptor {
     @objc(registerScreenCallbacksWithUUID:callbackQueue:frameCallback:surfacesChangedCallback:propertiesChangedCallback:)
     func registerScreenCallbacks(

package/Sources/SimNative/H264Encoder.swift

@@ -2,6 +2,7 @@ import Foundation
 import CoreVideo
 import CoreMedia
 import VideoToolbox
+import SimNativeSupport
 
 /// Real-time H.264 encoder backed by `VTCompressionSession`, producing AVCC
 /// (length-prefixed NAL) output for the `/stream.avcc` endpoint.
@@ -28,15 +29,15 @@ actor H264Encoder {
     private var width: Int32 = 0
     private var height: Int32 = 0
     private let fps: Int32
-    private var bitrate: Int
+    private let maxBitrate: Int?
     private var emittedDescription = false
     private var frameCount: Int64 = 0
 
     private let diagnostics: EncoderDiagnostics?
 
-    init(fps: Int = 60, bitrate: Int = 6_000_000, diagnostics: EncoderDiagnostics? = nil) {
+    init(fps: Int = 60, maxBitrate: Int? = nil, diagnostics: EncoderDiagnostics? = nil) {
         self.fps = Int32(fps)
-        self.bitrate = bitrate
+        self.maxBitrate = maxBitrate
         self.diagnostics = diagnostics
     }
 
@@ -144,7 +145,9 @@ actor H264Encoder {
             (kVTCompressionPropertyKey_RealTime, kCFBooleanTrue!),
             (kVTCompressionPropertyKey_ProfileLevel, kVTProfileLevel_H264_High_AutoLevel),
             (kVTCompressionPropertyKey_AllowFrameReordering, kCFBooleanFalse!),
-            (kVTCompressionPropertyKey_AverageBitRate, NSNumber(value: bitrate)),
+            (kVTCompressionPropertyKey_AverageBitRate, NSNumber(value: StreamBitrate.average(
+                width: Int(width), height: Int(height), fps: Int(fps), cap: maxBitrate
+            ))),
             (kVTCompressionPropertyKey_ExpectedFrameRate, NSNumber(value: fps)),
             // 5s keyframe interval: IDRs are far larger than P-frames, so
             // spacing them out keeps scroll/animation smooth. Late joiners

package/Sources/SimNative/sim-module.swift

@@ -117,13 +117,15 @@ private func u32(_ v: Int) -> UInt32 {
     private let engine: CaptureEngine
     private let queue: NodeAsyncQueue
 
-    @NodeConstructor init(_ udid: String) throws {
+    /// `maxBitrate`: optional cap (bits/s) on the resolution-scaled H.264
+    /// bitrate; null/undefined keeps the default.
+    @NodeConstructor init(_ udid: String, _ maxBitrate: Int?) throws {
         // unref'd by NodeAsyncQueue's init, so the frame pipeline alone won't
         // keep the event loop alive. Bounded queue + blocking AVCC preserves
         // inter-frame ordering; MJPEG is nonblocking and drops under backpressure.
         let queue = try NodeAsyncQueue(label: "simCapture", maxQueueSize: 16)
         self.queue = queue
-        self.engine = CaptureEngine(deviceUDID: udid)
+        self.engine = CaptureEngine(deviceUDID: udid, maxBitrate: maxBitrate)
     }
 
     // returns a function that can be called to unsubscribe
@@ -133,8 +135,10 @@ private func u32(_ v: Int) -> UInt32 {
     ) async throws -> NodeFunction {
         let codecMJPEG: Int = 0
         let codecAVCC: Int = 1
+        let codecSize: Int = 2
 
-        var buffer = try CaptureBuffer(initialCapacity: 1024 * 1024)
+        // Size-only subscriptions deliver an empty array; don't reserve 1 MB.
+        var buffer = try CaptureBuffer(initialCapacity: codec == codecSize ? 1 : 1024 * 1024)
         let unsubscribe: @Sendable () async -> Void
         switch codec {
         case codecMJPEG:
@@ -159,12 +163,32 @@ private func u32(_ v: Int) -> UInt32 {
                     ]).as(NodePromise.self)?.value
                 }
             }
+        case codecSize:
+            unsubscribe = await engine.addSizeConsumer { [self] dimensions in
+                try? await queue.run {
+                    let array = try buffer.setData(Data())
+                    _ = try? await onFrame.call([
+                        array,
+                        Int(dimensions.width), Int(dimensions.height),
+                        0,
+                    ]).as(NodePromise.self)?.value
+                }
+            }
         default:
             throw Errors.invalidCodec
         }
         return try NodeFunction { await unsubscribe() }
     }
 
+    /// JPEG of the latest frame (or null before the first frame), encoded on
+    /// demand for viewer seeds.
+    @NodeMethod func snapshotJpeg() async throws -> NodeValueConvertible {
+        guard let (_, jpeg) = try await engine.snapshotJPEG() else { return try NodeNull() }
+        let buffer = try NodeArrayBuffer(capacity: jpeg.count)
+        _ = try buffer.withUnsafeMutableBytes { jpeg.copyBytes(to: $0) }
+        return try NodeTypedArray<UInt8>(for: buffer, count: jpeg.count)
+    }
+
     @NodeMethod func setPreferredScreenSize(_ width: Int, _ height: Int) async {
         await engine.setPreferredScreenSize(width: width, height: height)
     }

package/Sources/SimNativeSupport/DevicePose.swift

@@ -30,10 +30,9 @@ public enum DevicePose {
         return nil
     }
 
+    /// Mirrors `DUO_POSES` in src/device-pose.ts: exactly closed, book, open.
     public static let presets: [DevicePoseSpec] = [
         DevicePoseSpec(name: "closed", hingeDegrees: 0),
-        DevicePoseSpec(name: "tent", hingeDegrees: 80),
-        DevicePoseSpec(name: "tabletop", hingeDegrees: 100),
         DevicePoseSpec(name: "book", hingeDegrees: 130),
         DevicePoseSpec(name: "open", hingeDegrees: 180),
     ]

package/Sources/SimNativeSupport/FramebufferSourceCache.swift

@@ -0,0 +1,58 @@
+/// Caches the framebuffer source (descriptor + IOSurface) that capture reads.
+///
+/// Resolving it means calling `framebufferSurface` on every display descriptor,
+/// and each call is a synchronous XPC round-trip into CoreSimulatorService
+/// (~2 ms each, 4 descriptors on an iPhone). Doing that on every frame callback
+/// put ~5 ms on the capture path of every frame. SimulatorKit keeps the same
+/// surface across frames and fires `surfacesChanged` when it swaps it, so frame
+/// callbacks reuse the cached source; everything else (surface changes, idle
+/// ticks, Duo panel/size changes) re-resolves. Frames reported by a descriptor
+/// other than the cached one re-resolve at most every 100 ms (another display
+/// became live), and a busy stream re-resolves every `maxAge` seconds as a
+/// safety net.
+public struct FramebufferSourceCache<Source> {
+    public enum Trigger: Sendable {
+        /// Frame callback from the cached source's descriptor.
+        case frame
+        /// Frame callback from any other descriptor.
+        case otherDescriptorFrame
+        case surfacesChanged
+        case idleTick
+        case preferredSizeChanged
+    }
+
+    private let maxAge: Double
+    static var otherDescriptorMaxAge: Double { 0.1 }
+    private var cached: Source?
+    private var resolvedAt = -Double.infinity
+
+    public init(maxAge: Double) {
+        self.maxAge = maxAge
+    }
+
+    public var current: Source? { cached }
+
+    public mutating func source(for trigger: Trigger, now: Double, resolve: () -> Source?) -> Source? {
+        let age = now - resolvedAt
+        if let cached {
+            switch trigger {
+            case .frame where age < maxAge,
+                 .otherDescriptorFrame where age < Self.otherDescriptorMaxAge:
+                return cached
+            default:
+                break
+            }
+        } else if trigger == .frame || trigger == .otherDescriptorFrame, age < Self.otherDescriptorMaxAge {
+            // The last resolve failed; don't repeat its XPC on every frame.
+            return nil
+        }
+        cached = resolve()
+        resolvedAt = now
+        return cached
+    }
+
+    public mutating func invalidate() {
+        cached = nil
+        resolvedAt = -Double.infinity
+    }
+}

package/Sources/SimNativeSupport/SeedRecheckSchedule.swift

@@ -0,0 +1,14 @@
+/// SimulatorKit can fire a frame callback before the framebuffer IOSurface's
+/// seed reflects the new frame (~13% of callbacks in measurement; the seed
+/// moved 1–16 ms later). Capture used to read the seed only after ~5 ms of
+/// per-frame XPC, which hid this. Without a re-check such a frame isn't
+/// emitted until the next idle tick (up to 200 ms later), so a callback that
+/// finds the seed unchanged re-checks on this schedule.
+public enum SeedRecheckSchedule {
+    static let delaysMs = [1, 1, 2, 4, 8, 16]
+
+    /// Delay before re-check number `attempt` (0-based), or nil to give up.
+    public static func delayMs(afterAttempt attempt: Int) -> Int? {
+        delaysMs.indices.contains(attempt) ? delaysMs[attempt] : nil
+    }
+}