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

package/README.md

@@ -113,6 +113,9 @@ serve-sim exec <command...> [-d udid] Run a host shell command through a server
                                       several are quoted as an argv
 serve-sim doctor [-d udid]            Collect redacted diagnostics for bug reports
                                       (--json, --out <file>)
+serve-sim record [-d udid]            Record the screen to an MP4 (native resolution,
+                                      60 fps H.264); Ctrl+C stops. -o <file>,
+                                      -t <duration>, --codec h264|hevc, --fps, --bitrate
 
 serve-sim camera <bundle-id> [-d udid] [source-options]
                                       Inject a synthetic camera feed and (re)launch the app
@@ -227,6 +230,17 @@ Sources:
 - **file** — image (PNG/JPEG/HEIC/…) or video (mp4/mov/m4v/webm/…). The CLI sniffs the kind from the extension and falls back to magic bytes for files without an extension.
 - **webcam** — live `AVCaptureDevice` (built-in, Continuity, external).
 
+### Screen recording
+
+The record button in the preview toolbar and `serve-sim record` both drive a native recorder in the server: it encodes the simulator framebuffer directly (full native resolution, constant frame rate, hardware H.264/HEVC), independent of the stream codec the viewer uses. Stopping streams the finished MP4 to the client that stopped it (a browser download, or the `-o` file) and deletes the server's temp copy. One recording runs per device; any client may stop it, and a `serve-sim record` whose recording is stopped elsewhere exits with an error instead of saving.
+
+A recording is capped at 30 minutes. At the cap the server finalizes the file and holds it for the client that started it, which collects it automatically. If that client has gone away (tab closed, `serve-sim record` killed), the hold lapses after 5 minutes: then any client may collect it with Stop, and starting a new recording discards it.
+
+Limitations:
+
+- **Rotation is fixed at start.** The file's orientation comes from the simulator's orientation when recording starts; rotating mid-recording leaves the rest of the footage sideways. Stop and start a new recording after rotating.
+- **Size changes freeze the video.** A track can't change dimensions, so if the screen size changes mid-recording (e.g. switching the Duo's active panel), frames at the new size are dropped and the rest of the video repeats the last frame at the original size.
+
 ## Connectors
 
 `serve-sim` can be used with dev servers, browser, and AI editors for more seamless integration.

package/Sources/SimNative/CaptureEngine.swift

@@ -17,6 +17,10 @@ struct Frame: Identifiable {
     /// (no pixel consumer was attached, so the private copy was skipped). Such
     /// frames are only good for their dimensions.
     var isPrivateCopy = true
+    /// Monotonic capture time (`DispatchTime` uptime, seconds) taken when
+    /// FrameCapture read the surface; screen recordings are timed from this
+    /// rather than from when the frame reached a consumer.
+    var captureTime: Double = Double(DispatchTime.now().uptimeNanoseconds) / 1e9
 }
 
 protocol FrameEncoder {
@@ -144,8 +148,16 @@ actor CaptureEngine {
             bufferingPolicy: .bufferingNewest(1)
         )
         do {
-            try await frameCapture.start(deviceUDID: deviceUDID, pixelConsumers: pixelConsumers) { pixelBuffer, _, isCopy in
-                frameContinuation.yield(Frame(pixelBuffer: pixelBuffer, isPrivateCopy: isCopy))
+            try await frameCapture.start(deviceUDID: deviceUDID, pixelConsumers: pixelConsumers) { [recorderTap] pixelBuffer, timestamp, isCopy in
+                let frame = Frame(
+                    pixelBuffer: pixelBuffer,
+                    isPrivateCopy: isCopy,
+                    captureTime: timestamp.seconds
+                )
+                // The recorder needs every frame, so it's fed here rather
+                // than through the newest-only stream the live encoders share.
+                recorderTap.recorder?.handleFrame(frame)
+                frameContinuation.yield(frame)
             }
         } catch {
             // Preserve retryability after an ordinary start failure, but never
@@ -268,9 +280,55 @@ actor CaptureEngine {
         }
     }
 
+    // MARK: - Recording
+
+    /// The active recorder, read by FrameCapture's frame callback.
+    private let recorderTap = RecorderTap()
+    private var recording: ScreenRecorder?
+
+    var isRecording: Bool { recording != nil }
+
+    /// Start recording the screen to an MP4 at `options.path`. One recording
+    /// per capture session; it counts as a pixel consumer, so frames are
+    /// copied (and timestamped) for it even when no viewer is attached.
+    func startRecording(_ options: ScreenRecorder.Options) throws {
+        guard phase == .running else { throw RecordingErrors.notRunning }
+        guard recording == nil else { throw RecordingErrors.alreadyRecording }
+        let recorder = ScreenRecorder(options: options)
+        pixelConsumers.increment()
+        recording = recorder
+        recorderTap.recorder = recorder
+        Task { [frameCapture] in await frameCapture.requestFrame() }
+    }
+
+    /// Finish the active recording; returns its JSON summary.
+    func stopRecording() async throws -> String {
+        guard let recorder = recording else { throw RecordingErrors.notRecording }
+        recording = nil
+        recorderTap.recorder = nil
+        pixelConsumers.decrement()
+        return try await recorder.finish()
+    }
+
+    enum RecordingErrors: Error, CustomStringConvertible {
+        case notRunning, alreadyRecording, notRecording
+        var description: String {
+            switch self {
+            case .notRunning: return "Capture is not running"
+            case .alreadyRecording: return "A recording is already in progress"
+            case .notRecording: return "No recording in progress"
+            }
+        }
+    }
+
     func stop() {
         if phase == .stopped { return }
         phase = .stopped
+        if let recorder = recording {
+            recorderTap.recorder = nil
+            recorder.cancel()
+            recording = nil
+        }
         Task { [frameCapture] in await frameCapture.stop() }
         consumers.removeAll()
         pixelConsumers.reset()
@@ -331,3 +389,16 @@ actor AVCCEncoder: FrameEncoder {
         Task { [h264Encoder] in await h264Encoder.stop() }
     }
 }
+
+/// Lock-protected handle on the active `ScreenRecorder`, shared between the
+/// engine actor (which sets it) and FrameCapture's frame callback (which
+/// hands it every captured frame without an actor hop).
+private final class RecorderTap: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _recorder: ScreenRecorder?
+
+    var recorder: ScreenRecorder? {
+        get { lock.withLock { _recorder } }
+        set { lock.withLock { _recorder = newValue } }
+    }
+}

package/Sources/SimNative/FrameCapture.swift

@@ -54,7 +54,7 @@ actor FrameCapture {
     private var sourceCache = FramebufferSourceCache<FramebufferSource>(maxAge: 1.0)
     private var recheckGeneration: UInt64 = 0
 
-    /// `onFrame(buffer, timestamp, isPrivateCopy)`: frames are deep-copied only
+    /// `onFrame(buffer, captureTime, 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(
@@ -370,7 +370,8 @@ actor FrameCapture {
 
         lastCaptureTime = .now
         frameCount += 1
-        let timestamp = CMTime(value: CMTimeValue(frameCount), timescale: 60)
+        // Monotonic capture time (uptime ns): recordings place frames by it.
+        let timestamp = CMTime(value: CMTimeValue(DispatchTime.now().uptimeNanoseconds), timescale: 1_000_000_000)
         if pixelConsumers?.isEmpty ?? false {
             onFrame?(pb, timestamp, false)
             return true

package/Sources/SimNative/PixelBufferUtils.swift

@@ -54,8 +54,12 @@ struct Photocopier {
         let dstStride = CVPixelBufferGetBytesPerRow(dst)
         let rows = CVPixelBufferGetHeight(source)
         let copyBytes = min(srcStride, dstStride)
-        for row in 0..<rows {
-            memcpy(dstAddr + row * dstStride, srcAddr + row * srcStride, copyBytes)
+        if srcStride == dstStride {
+            memcpy(dstAddr, srcAddr, srcStride * rows)
+        } else {
+            for row in 0..<rows {
+                memcpy(dstAddr + row * dstStride, srcAddr + row * srcStride, copyBytes)
+            }
         }
         return dst
     }

package/Sources/SimNative/ScreenRecorder.swift

@@ -0,0 +1,300 @@
+import Foundation
+import AVFoundation
+import CoreMedia
+import CoreVideo
+import SimNativeSupport
+
+/// Records the captured simulator screen straight to an MP4 with
+/// AVAssetWriter (VideoToolbox hardware H.264/HEVC).
+///
+/// Frames are the private BGRA copies FrameCapture already makes for the live
+/// encoders: full native resolution, no MJPEG/stream re-encode, no scaling.
+/// Each frame is placed on a constant `fps` grid by its capture time
+/// (`RecordingFrameScheduler`), repeating the previous frame across static
+/// stretches, so the file is true CFR whose motion timing follows the
+/// simulator rather than the encoder or JS event loop. Static slots are filled
+/// as time passes by a frame-interval timer on `queue` that never waits on the
+/// encoder, so the first frames of new motion don't queue up behind seconds of
+/// repeats (and get shed by the backlog cap).
+///
+/// All writer state is confined to `queue`. `handleFrame` only enqueues, so a
+/// slow encoder never stalls capture or the live stream consumers; the
+/// backlog is capped (`maxPendingFrames`) so a stalled encoder can't pin an
+/// unbounded number of full-resolution buffers.
+final class ScreenRecorder: CaptureConsuming, @unchecked Sendable {
+    struct Options {
+        var path: String
+        var codec: AVVideoCodecType = .h264
+        var fps: Int = 60
+        /// Clockwise display rotation (0, 90, 180, 270/-90) stored as the
+        /// track transform. The framebuffer itself is always native portrait.
+        var rotationDegrees: Int = 0
+        /// Average bitrate (bits/s); nil scales with the pixel rate.
+        var bitrate: Int?
+    }
+
+    enum Errors: Error, CustomStringConvertible {
+        case noFrames
+        case writerFailed(String)
+
+        var description: String {
+            switch self {
+            case .noFrames: return "No frames were captured"
+            case .writerFailed(let message): return "Recording failed: \(message)"
+            }
+        }
+    }
+
+    /// ~200 ms at 60 fps; each pending frame holds a full-res BGRA copy.
+    static let maxPendingFrames = 12
+
+    private let queue = DispatchQueue(label: "screen-recorder", qos: .userInitiated)
+    private let pendingFrames = PendingFrameLimiter(limit: ScreenRecorder.maxPendingFrames)
+    private let options: Options
+    private let startedAt = Date()
+
+    // queue-confined
+    private var writer: AVAssetWriter?
+    private var input: AVAssetWriterInput?
+    private var adaptor: AVAssetWriterInputPixelBufferAdaptor?
+    private var scheduler: RecordingFrameScheduler
+    private var dimensions: Dimensions?
+    private var lastBuffer: CVPixelBuffer?
+    private var fillTimer: DispatchSourceTimer?
+    private var bitrate = 0
+    private var finished = false
+    private var failure: String?
+    private var captured = 0
+    private var encoded = 0
+    private var repeated = 0
+    private var dropped = 0
+    private var encoderBusy = 0
+
+    init(options: Options) {
+        self.options = options
+        self.scheduler = RecordingFrameScheduler(fps: options.fps)
+    }
+
+    func handleFrame(_ frame: Frame) {
+        guard frame.isPrivateCopy else { return }
+        // Over the cap the frame is dropped here (counted in `backlogDropped`);
+        // the CFR scheduler repeats the previous frame across the gap.
+        guard pendingFrames.tryAcquire() else { return }
+        queue.async {
+            defer { self.pendingFrames.release() }
+            self.append(frame)
+        }
+    }
+
+    /// Pad to "now", close the file, and return a JSON summary.
+    func finish() async throws -> String {
+        let stopTime = Self.now()
+        return try await withCheckedThrowingContinuation { continuation in
+            queue.async {
+                self.finish(at: stopTime) { result in continuation.resume(with: result) }
+            }
+        }
+    }
+
+    /// Abandon the recording and remove the partial file.
+    func cancel() {
+        queue.async {
+            self.finished = true
+            self.stopFillTimer()
+            if let writer = self.writer, writer.status == .writing { writer.cancelWriting() }
+            try? FileManager.default.removeItem(atPath: self.options.path)
+        }
+    }
+
+    // MARK: - queue
+
+    private func append(_ frame: Frame) {
+        guard !finished, failure == nil else { return }
+        captured += 1
+        let size = frame.pixelBuffer.dimensions
+        if let dimensions {
+            // A mid-recording size change (Duo panel switch, Device Hub
+            // resize) can't go in the same track; keep the original size.
+            guard size == dimensions else { dropped += 1; return }
+        } else {
+            do { try startWriter(size) } catch {
+                failure = String(describing: error)
+                return
+            }
+        }
+        guard let placement = scheduler.place(captureTime: frame.captureTime) else {
+            dropped += 1
+            return
+        }
+        // Normally empty: the fill timer already covered the static stretch.
+        if let lastBuffer {
+            for slot in placement.repeats where write(lastBuffer, slot: slot) { repeated += 1 }
+        }
+        if write(frame.pixelBuffer, slot: placement.slot) { encoded += 1 }
+        lastBuffer = frame.pixelBuffer
+    }
+
+    private func startWriter(_ size: Dimensions) throws {
+        let url = URL(fileURLWithPath: options.path)
+        try? FileManager.default.removeItem(at: url)
+        let writer = try AVAssetWriter(outputURL: url, fileType: .mp4)
+        // moov up front so browsers can play the download progressively.
+        writer.shouldOptimizeForNetworkUse = true
+        let bitrate = options.bitrate ?? RecordingBitrate.average(
+            width: size.width, height: size.height, fps: options.fps
+        )
+        var compression: [String: Any] = [
+            AVVideoAverageBitRateKey: bitrate,
+            AVVideoExpectedSourceFrameRateKey: options.fps,
+            AVVideoMaxKeyFrameIntervalKey: options.fps * 2,
+            AVVideoAllowFrameReorderingKey: true,
+        ]
+        if options.codec == .h264 {
+            compression[AVVideoProfileLevelKey] = AVVideoProfileLevelH264HighAutoLevel
+        }
+        let settings: [String: Any] = [
+            AVVideoCodecKey: options.codec,
+            AVVideoWidthKey: size.width,
+            AVVideoHeightKey: size.height,
+            AVVideoCompressionPropertiesKey: compression,
+            // The simulator renders Display P3 with the sRGB curve; tag the
+            // file the same way `simctl io recordVideo` does so colors match.
+            AVVideoColorPropertiesKey: [
+                AVVideoColorPrimariesKey: AVVideoColorPrimaries_P3_D65,
+                // AVVideoTransferFunction_IEC_sRGB (macOS 15+ symbol; same value).
+                AVVideoTransferFunctionKey: "IEC_sRGB",
+                AVVideoYCbCrMatrixKey: AVVideoYCbCrMatrix_ITU_R_709_2,
+            ],
+        ]
+        let input = AVAssetWriterInput(mediaType: .video, outputSettings: settings)
+        input.expectsMediaDataInRealTime = true
+        input.transform = Self.transform(rotationDegrees: options.rotationDegrees)
+        let adaptor = AVAssetWriterInputPixelBufferAdaptor(
+            assetWriterInput: input,
+            sourcePixelBufferAttributes: [
+                kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA,
+                kCVPixelBufferWidthKey as String: size.width,
+                kCVPixelBufferHeightKey as String: size.height,
+            ]
+        )
+        guard writer.canAdd(input) else { throw Errors.writerFailed("cannot add video input") }
+        writer.add(input)
+        guard writer.startWriting() else {
+            throw Errors.writerFailed(writer.error.map { String(describing: $0) } ?? "startWriting failed")
+        }
+        writer.startSession(atSourceTime: .zero)
+        self.writer = writer
+        self.input = input
+        self.adaptor = adaptor
+        self.dimensions = size
+        self.bitrate = bitrate
+        startFillTimer()
+        print("[record] Recording \(size.width)x\(size.height) @ \(options.fps) fps \(options.codec.rawValue) \(bitrate / 1000) kbps -> \(options.path)")
+    }
+
+    private static func now() -> Double {
+        Double(DispatchTime.now().uptimeNanoseconds) / 1e9
+    }
+
+    private func startFillTimer() {
+        let interval = DispatchTimeInterval.nanoseconds(Int(1_000_000_000 / options.fps))
+        let timer = DispatchSource.makeTimerSource(queue: queue)
+        timer.schedule(deadline: .now() + interval, repeating: interval, leeway: .milliseconds(1))
+        timer.setEventHandler { [weak self] in self?.fillStaticSlots() }
+        timer.resume()
+        fillTimer = timer
+    }
+
+    private func stopFillTimer() {
+        fillTimer?.cancel()
+        fillTimer = nil
+    }
+
+    /// Repeat the last frame into the slots that have gone by with no new
+    /// frame. Usually one slot per tick. Never waits on the encoder: a slot it
+    /// can't write yet stays owed to the next tick (or the next frame's
+    /// placement), so the queue stays free for captured frames. Skipped while
+    /// frames wait behind a slow encoder: their slots must stay open.
+    private func fillStaticSlots() {
+        guard !finished, failure == nil, let lastBuffer else { return }
+        for slot in scheduler.repeatsDue(at: Self.now(), framesPending: pendingFrames.pending) {
+            guard write(lastBuffer, slot: slot, waitForEncoder: false) else { break }
+            scheduler.didFill(through: slot)
+            repeated += 1
+        }
+    }
+
+    @discardableResult
+    private func write(_ buffer: CVPixelBuffer, slot: Int64, waitForEncoder: Bool = true) -> Bool {
+        guard let writer, let input, let adaptor, failure == nil else { return false }
+        // We're on the recorder's own queue, so waiting here only delays the
+        // recording, never capture or the live stream. Real-time inputs may
+        // briefly refuse data while the hardware encoder catches up.
+        var waitedMs = 0
+        while waitForEncoder, !input.isReadyForMoreMediaData, waitedMs < 250, writer.status == .writing {
+            usleep(1000)
+            waitedMs += 1
+        }
+        guard input.isReadyForMoreMediaData else {
+            if waitForEncoder { encoderBusy += 1 }
+            return false
+        }
+        let pts = CMTime(value: slot, timescale: CMTimeScale(options.fps))
+        guard adaptor.append(buffer, withPresentationTime: pts) else {
+            failure = writer.error.map { String(describing: $0) } ?? "append failed"
+            return false
+        }
+        return true
+    }
+
+    private func finish(at stopTime: Double, completion: @escaping (Result<String, Error>) -> Void) {
+        guard !finished else { return completion(.failure(Errors.writerFailed("already finished"))) }
+        finished = true
+        stopFillTimer()
+        guard let writer, let input, let lastBuffer, let end = scheduler.finish(at: stopTime) else {
+            if let writer, writer.status == .writing { writer.cancelWriting() }
+            try? FileManager.default.removeItem(atPath: options.path)
+            return completion(.failure(failure.map(Errors.writerFailed) ?? Errors.noFrames))
+        }
+        for slot in end.repeats where write(lastBuffer, slot: slot) { repeated += 1 }
+        input.markAsFinished()
+        let fps = options.fps
+        writer.endSession(atSourceTime: CMTime(value: end.endSlot, timescale: CMTimeScale(fps)))
+        let summary: [String: Any] = [
+            "path": options.path,
+            "width": dimensions?.width ?? 0,
+            "height": dimensions?.height ?? 0,
+            "fps": fps,
+            "codec": options.codec == .hevc ? "hevc" : "h264",
+            "bitrate": bitrate,
+            "rotation": options.rotationDegrees,
+            "frames": Int(end.endSlot),
+            "duration": Double(end.endSlot) / Double(fps),
+            "captured": captured,
+            "encoded": encoded,
+            "repeated": repeated,
+            "dropped": dropped + pendingFrames.dropped,
+            "backlogDropped": pendingFrames.dropped,
+            "encoderBusy": encoderBusy,
+            "startedAt": isoTimestamp(startedAt),
+        ]
+        writer.finishWriting {
+            if writer.status == .completed {
+                print("[record] Saved \(self.options.path) (\(summary["frames"] ?? 0) frames, \(self.captured) captured, \(self.repeated) repeated, \(self.dropped + self.pendingFrames.dropped) dropped)")
+                completion(.success(jsonString(summary)))
+            } else {
+                let message = writer.error.map { String(describing: $0) } ?? "status \(writer.status.rawValue)"
+                completion(.failure(Errors.writerFailed(message)))
+            }
+        }
+    }
+
+    private static func transform(rotationDegrees: Int) -> CGAffineTransform {
+        switch ((rotationDegrees % 360) + 360) % 360 {
+        case 90: return CGAffineTransform(rotationAngle: .pi / 2)
+        case 180: return CGAffineTransform(rotationAngle: .pi)
+        case 270: return CGAffineTransform(rotationAngle: -.pi / 2)
+        default: return .identity
+        }
+    }
+}

package/Sources/SimNative/sim-module.swift

@@ -203,6 +203,25 @@ private func u32(_ v: Int) -> UInt32 {
         await engine.diagnostics()
     }
 
+    /// Start an MP4 screen recording at `path`. `codec` is "h264" or "hevc";
+    /// `rotation` is the clockwise display rotation stored as the track
+    /// transform; `bitrate` <= 0 picks the resolution-scaled default.
+    @NodeMethod func startRecording(
+        _ path: String, _ codec: String, _ fps: Int, _ rotation: Int, _ bitrate: Int
+    ) async throws {
+        var options = ScreenRecorder.Options(path: path)
+        options.codec = codec == "hevc" ? .hevc : .h264
+        options.fps = min(max(fps, 1), 120)
+        options.rotationDegrees = rotation
+        options.bitrate = bitrate > 0 ? bitrate : nil
+        try await engine.startRecording(options)
+    }
+
+    /// Finish the active recording; resolves with a JSON summary string.
+    @NodeMethod func stopRecording() async throws -> String {
+        try await engine.stopRecording()
+    }
+
     @NodeMethod func stop() async {
         await engine.stop()
     }

package/Sources/SimNativeSupport/PendingFrameLimiter.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// Thread-safe cap on frames queued for a slow consumer (the screen
+/// recorder's writer queue). Each queued frame pins a full-resolution pixel
+/// buffer, so when the encoder falls behind we drop new frames rather than
+/// let the backlog grow without bound.
+public final class PendingFrameLimiter: @unchecked Sendable {
+    public let limit: Int
+    private let lock = NSLock()
+    private var _pending = 0
+    private var _dropped = 0
+
+    public init(limit: Int) {
+        self.limit = max(1, limit)
+    }
+
+    /// Reserve a slot for one frame; false (and counted as dropped) when full.
+    public func tryAcquire() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard _pending < limit else {
+            _dropped += 1
+            return false
+        }
+        _pending += 1
+        return true
+    }
+
+    /// Free the slot once the frame has been handled.
+    public func release() {
+        lock.lock()
+        _pending = max(0, _pending - 1)
+        lock.unlock()
+    }
+
+    public var pending: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return _pending
+    }
+
+    public var dropped: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return _dropped
+    }
+}

package/Sources/SimNativeSupport/RecordingBitrate.swift

@@ -0,0 +1,17 @@
+/// Average bitrate for screen recordings.
+///
+/// Recordings are archival, not latency-bound, so they get twice the live
+/// stream's 0.1 bits/pixel (~38 Mbps for an iPhone Pro at 60 fps). That is a
+/// ceiling, not a constant rate: static stretches are repeated frames that
+/// encode to skip blocks, so typical UI recordings land far below it.
+public enum RecordingBitrate {
+    public static let minimum = 8_000_000
+    public static let maximum = 80_000_000
+    static let bitsPerPixel = 0.2
+
+    public static func average(width: Int, height: Int, fps: Int) -> Int {
+        guard width > 0, height > 0, fps > 0 else { return minimum }
+        let target = Int(Double(width * height * fps) * bitsPerPixel)
+        return min(max(target, minimum), maximum)
+    }
+}

package/Sources/SimNativeSupport/RecordingFrameScheduler.swift

@@ -0,0 +1,111 @@
+/// Places captured simulator frames on a constant-frame-rate grid for screen
+/// recordings.
+///
+/// SimulatorKit only fires a frame callback when the screen changes, so the
+/// raw capture is variable-rate: ~60 fps while scrolling, nothing at all while
+/// the screen is static, and jittered by a few ms either way. A recording
+/// stamped with raw capture times plays back fine in some players, but editors
+/// and browsers handle sparse VFR poorly and tooling reports a meaningless
+/// frame rate. Instead each frame is snapped to the nearest slot of a fixed
+/// `fps` grid measured from the first frame's capture time, and empty slots
+/// are filled by repeating the previous frame (cheap: H.264/HEVC encode an
+/// unchanged frame as skip blocks). The result is true CFR whose motion timing
+/// still follows the actual capture clock, not frame arrival order.
+///
+/// Jitter handling: SimulatorKit often delivers frames in bursts (two or
+/// three distinct frames a couple of ms apart after a compositor hiccup), so a
+/// frame whose rounded slot is already taken moves to the next free slot as
+/// long as that keeps it less than `maxLag` frame intervals behind its real
+/// capture time. A few frames of lag is invisible in a recording and catches
+/// up at the next pause; a dropped frame is a visible stutter. Only a source
+/// that sustains more than `fps` (e.g. a 120 Hz burst) falls further behind,
+/// and those frames are dropped rather than letting the timeline drift.
+///
+/// Static fill: the recorder doesn't wait for the next frame to repeat the
+/// previous one across a static stretch (that would make the first frame of
+/// new motion write seconds of repeats first while the frames behind it pile
+/// up). A frame-interval timer instead fills `repeatsDue(at:framesPending:)` as time passes,
+/// leaving `fillHeadroom` slots open for a frame that was captured but not yet
+/// delivered, and commits what it wrote with `didFill(through:)`.
+public struct RecordingFrameScheduler: Sendable {
+    /// Where to append a captured frame.
+    public struct Placement: Equatable, Sendable {
+        /// Slots to fill with the previously appended frame first, in order.
+        public let repeats: Range<Int64>
+        /// Slot (presentation time = slot / fps) for the new frame.
+        public let slot: Int64
+    }
+
+    /// Frame intervals a frame may be placed after its capture time.
+    public static let defaultMaxLag = 3.0
+
+    /// Slots the static fill leaves open behind "now".
+    public static let defaultFillHeadroom: Int64 = 2
+
+    public let fps: Int
+    public let maxLag: Double
+    public let fillHeadroom: Int64
+    private var origin: Double?
+    private var lastSlot: Int64 = -1
+
+    public init(fps: Int, maxLag: Double = defaultMaxLag, fillHeadroom: Int64 = defaultFillHeadroom) {
+        precondition(fps > 0, "fps must be positive")
+        precondition(maxLag >= 1, "maxLag must allow at least the next slot")
+        precondition(fillHeadroom >= 1, "fillHeadroom must leave the current slot open")
+        self.fps = fps
+        self.maxLag = maxLag
+        self.fillHeadroom = fillHeadroom
+    }
+
+    /// Number of slots written so far (the next free slot).
+    public var slotCount: Int64 { lastSlot + 1 }
+
+    /// Place a frame captured at `time` (seconds on a monotonic clock). Returns
+    /// nil when the frame should be dropped.
+    public mutating func place(captureTime time: Double) -> Placement? {
+        guard let origin else {
+            self.origin = time
+            lastSlot = 0
+            return Placement(repeats: 0..<0, slot: 0)
+        }
+        let exact = (time - origin) * Double(fps)
+        var slot = Int64(exact.rounded())
+        if slot <= lastSlot {
+            // Nudge a jittered/bursty frame into the next slot, but never
+            // more than `maxLag` intervals after it was really captured.
+            let next = lastSlot + 1
+            guard Double(next) - exact < maxLag else { return nil }
+            slot = next
+        }
+        let repeats = (lastSlot + 1)..<slot
+        lastSlot = slot
+        return Placement(repeats: repeats, slot: slot)
+    }
+
+    /// Static slots to repeat the last frame into by `time`: everything up to
+    /// `fillHeadroom` slots behind it. Empty before the first frame, and while
+    /// captured frames are still queued for the writer (`framesPending > 0`):
+    /// under encoder backlog "now" can run past those frames' slots, and the
+    /// next one placed covers the gap with its own repeats anyway.
+    public func repeatsDue(at time: Double, framesPending: Int = 0) -> Range<Int64> {
+        guard let origin, framesPending == 0 else { return lastSlot + 1..<lastSlot + 1 }
+        let target = Int64(((time - origin) * Double(fps)).rounded(.down)) - fillHeadroom
+        return (lastSlot + 1)..<max(lastSlot + 1, target + 1)
+    }
+
+    /// Record that the static fill wrote every slot through `slot`.
+    public mutating func didFill(through slot: Int64) {
+        lastSlot = max(lastSlot, slot)
+    }
+
+    /// Slots to fill with the last frame so the recording runs until `time`,
+    /// plus the end time (in slots) to close the session at. Nil when no frame
+    /// was ever placed.
+    public mutating func finish(at time: Double) -> (repeats: Range<Int64>, endSlot: Int64)? {
+        guard let origin else { return nil }
+        let target = Int64(((time - origin) * Double(fps)).rounded(.down))
+        let repeats = (lastSlot + 1)..<max(lastSlot + 1, target + 1)
+        if let last = repeats.last { lastSlot = last }
+        return (repeats, lastSlot + 1)
+    }
+}